ConvAPI

ConvAPI allows easy HTTP requests in Swift against REST-style APIs with JSON formatting by supporting codable bodies and promised responses.

Etymology

ConvAPI (/kənˈveɪ-piː-aɪ/) is a contraction of Convey (to carry, bring, or take from one place to another) and API (Application Programming Interface).

Usage

ConvAPI has the method

func request<T, U, E>(method:APIMethod,
baseURL:URL,
resource:String,
headers:[String:String]?,
params:[String:Any]?,
body:T?,
error:E.Type,
decorator:((inoutURLRequest)->Void)?)asyncthrows->U

where T: Encodable, U: Decodable, E: (Error & Decodable) at its core.

This method allows you to asynchronously request a resource from an API specifying the

• method (e.g. GET),
• baseURL,
• resource URI (e.g. /users/42),
• http headers as a dictionary,
• query params as a dictionary,
• request body (any type that conforms to Encodable),
• an error struct (Decodable) your API might respond with and,
• a decorator to access/alter the URLRequest that gets fired underneath

and getting the response with a type (U) conforming to Decodable. All of the error handling (status code, empty response, etc.) and parsing is done for you.

Requesting a resource

Request a resource by specifying

structUser:Codable{letid:Intletname:String}letapi=ConvAPI()letbaseURL=URL(string:"https://jsonplaceholder.typicode.com")!
letuser:User=tryawait api.request(method:.GET, baseURL: baseURL, resource:"/users/1", error:ConvAPIError.self)print(user) // User(id: 1, name: "Leanne Graham")

Specifying an error

If your API has an error JSON it is responsing with, just define your error response and hand it in:

structMyAPIError:Error,Codable{letcode:Intletmessage:String}do{letuser:User=tryawait api.request(method:.GET, baseURL: baseURL, resource:"/users/1", error:MyAPIError.self)
// [...]
}catch{switch error {caseleterror as MyAPIError:print(error.code)default:break // Request error, network down, etc.
}}

Swift Package Manager

.package(url:"https://github.com/ChaosCoder/ConvAPI.git", from:"1.0.0")