Skip to content

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

License

Notifications You must be signed in to change notification settings

ChaosCoder/ConvAPI

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

51 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

ConvAPI

Build Status

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: ((inout URLRequest) -> Void)?) async throws -> 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

struct User: Codable {
    let id: Int
    let name: String
}
        
let api = ConvAPI()
let baseURL = URL(string: "https://jsonplaceholder.typicode.com")!
let user: User = try await 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:

struct MyAPIError: Error, Codable {
    let code: Int
    let message: String
}

do {
    let user: User = try await api.request(method: .GET, baseURL: baseURL, resource: "/users/1", error: MyAPIError.self)
    // [...]
} catch {
    switch error {
        case let error 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")

About

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

Topics

Resources

License

Stars

Watchers

Forks

Packages

No packages published