Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/chaoscoder/convapi
ConvAPI allows easy HTTP requests in Swift against REST-style APIs with JSON formatting by supporting codable bodies and promised responses.
https://github.com/chaoscoder/convapi
json-api swift
Last synced: about 2 months ago
JSON representation
ConvAPI allows easy HTTP requests in Swift against REST-style APIs with JSON formatting by supporting codable bodies and promised responses.
- Host: GitHub
- URL: https://github.com/chaoscoder/convapi
- Owner: ChaosCoder
- License: mit
- Created: 2018-04-15T14:37:36.000Z (almost 7 years ago)
- Default Branch: master
- Last Pushed: 2024-01-28T12:08:03.000Z (12 months ago)
- Last Synced: 2024-12-02T03:40:32.626Z (about 2 months ago)
- Topics: json-api, swift
- Language: Swift
- Homepage:
- Size: 115 KB
- Stars: 3
- Watchers: 4
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
README
# ConvAPI
[]() []() [](LICENSE.md) [](https://app.bitrise.io/app/9bd0d2e769e903f9)
ConvAPI allows easy [HTTP](https://tools.ietf.org/html/rfc7231) requests in [Swift](https://swift.org) against [REST](https://en.wikipedia.org/wiki/Representational_state_transfer)-style [APIs](https://en.wikipedia.org/wiki/Application_programming_interface) with [JSON](https://www.json.org/) formatting by supporting [codable](https://developer.apple.com/documentation/swift/codable) bodies and [promised](https://github.com/mxcl/PromiseKit) 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
```swift
func request(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
```swift
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:
```swift
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
```swift
.package(url: "https://github.com/ChaosCoder/ConvAPI.git", from: "1.0.0")
```