![alt [version]](https://img.shields.io/github/v/release/neothXT/Snowdrop)
Meet Snowdrop - type-safe, easy to use framework powered by Swift Macros created to let you build and maintain complex network requests with ease.
Snowdrop is available via SPM. It works with iOS Deployment Target has to be 14.0 or newer. If you code for macOS, your Deployment Target has to be 11 or newer.
- Type-safe service creation with
@Servicemacro - Support for various request method types such as
@GET@POST@PUT@DELETE@PATCH@CONNECT@HEAD@OPTIONS@QUERY@TRACE
- SSL/Certificate pinning
- Interceptors
Creating network services with Snowdrop is really easy. Just declare a protocol along with its functions.
@Service
protocol MyEndpoint {
@GET(url: "/posts")
@Headers(["X-DeviceID": "testSim001"])
func getAllPosts() async throws -> [Post]
}If your request includes some dynamic values, such as id, you can add it to your path wrapping it with {}. Snowdrop will automatically bind your function declaration's arguments with those you include in request's path.
@GET(url: "/posts/{id}")
func getPost(id: Int) async throws -> PostUpon expanding macros, Snowdrop creates a class MyEndpointService which implements MyEndpoint protocol and generates all the functions you declared.
class MyEndpointService: MyEndpoint {
func getAllPosts() async throws -> [Post] {
// auto-generated body
}
func getPost(id: Int) async throws -> Post {
// auto-generated body
}
}To send requests, just initialize MyEndpointService instance and call function corresponding to the request you want to execute.
let service = MyEndpointService(baseUrl: URL(string: "https://my-endpoint.com")!)
let post = try await getPost(id: 7)Snowdrop's config allows you to set/change framework's global settings.
If you need to change default json decoder, you can set your own decoder to Snowdrop.Config.defaultJSONDecoder.
To enable SSL/Certificate Pinning all you need to do is to include your certificate in the project.
Then, if you want to exclude some URLs from SSL/Certificate pinning, add them to Snowdrop.Config.urlsExcludedFromPinning.
If you want to put some encodable object as a body of your request, you can either put it in your declaration as "body" argument or - if you want to use another name - use @Body macro like:
@POST(url: "/posts")
@Body("model")
func addPost(model: Post) async throws -> DataIf you want to declare service's function that sends some file to the server as multipart/form-data, use @FileUpload macro. It'll automatically add Content-Type: multipart/form-data to the request's headers and extend the list of your function's arguments with _payloadDescription: PayloadDescription which you should then use to provide information such as name, fileName and mimeType.
@Service
protocol MyEndpoint {
@FileUpload
@Body("image")
@POST(url: "/uploadAvatar/")
func uploadImage(_ image: UIImage) async throws -> Data
}
let payload = PayloadDescription(name: "avatar", fileName: "filename.jpeg", mimeType: "image/jpeg")
let service = MyEndpointService(baseUrl: URL(string: "https://my-endpoint.com")!)
_ = try await service.uploadImage(someImage, _payloadDescription: payload)Upon expanding macros, Snowdrop adds argument _queryItems: [QueryItem] to every service's function. For dynamic query parameters it's recommended to pass them using this argument like:
@Service
protocol MyEndpoint {
@GET(url: "/posts/{id}")
func getPost(id: Int) async throws -> Post
}
let authorName = "John Smith"
let service = MyEndpointService(baseUrl: URL(string: "https://my-endpoint.com")!)
let post = try await service.getPost(id: 7, _queryItems: [.init(key: "author", value: authorName)])Snowdrop allows you to define custom values for your arguments. Let's say your path includes {id} argument. As you already know by now, Snowdrop automatically associates it with id argument of your func declaration. If you want it to have default value equal "3", do it like: {id=3}. Be careful though as Snowdrop won't check if your default value's type conforms to the declaration.
Each service provides two static interceptors - beforeSending and onResponse. You should use them like:
MyEndpointService.beforeSending = { request in
// some operations
return request
}
MyEndpointService.onResponse = { data, urlResponse in
// some operations
return data
}Those interceptors are then called for each MyEndpointService function's call.
Retrofit was an inspiration for Snowdrop.