A leightweigth REST API request generator library for Swift.
RetroSwift supports Swift Package Manager.
To install RetroSwift using Swift Package Manager you can follow the tutorial published by Apple using the URL for the RetroSwift repo with the current version:
- In Xcode, select “File” → “Add Packages...”
- Enter https://github.com/rmichelberger/RetroSwift
or you can add the following dependency to your Package.swift:
.package(url: "https://github.com/rmichelberger/RetroSwift/", from: "1.0.0")You can create HTTP requests the following way.
First, you need to define the base URL as String and the HTTP method.
Example:
let baseUrl = "https://example.com"
@GET(baseURL: baseUrl) var requestYou can also optionally define a path.
@Path(path: "/my/path") var pathYou can also define dynamic parameters in the path.
Example:
let id = 123
@Path(path: "/api/v1/items/{id}", name: "id") var path = idor
let id = "xyz"
@Path(path: "/api/v1/items/{parameter}", name: "parameter") var path = idThe parameter must implement the CustomStringConvertible protocol.
@Query(name: "name") var query = 123or
@Query(name: "name") var query = "value"The name needs to be a String, and the value must implement the CustomStringConvertible protocol.
@Body(value: value) var bodyThe value must implement the Encodable protocol.
You can also define your own DataEncoder, the default one is JSONEncoder.
@Body(value: value, encoder: encoder) var bodyYou can add the body to the HTTP request:
func getItem(id: Int) async throws -> Item {
let baseUrl = "https://example.com"
@Path(path: "/api/v1/items/{id}", name: "id") var path = id
let user = ["Name": "John Doe"]
@Body(value: user) var body
@POST(baseURL: baseUrl, path: path, body: body) var request
return try await retroSwift.execute(request: request)
}You can specify the headers as following:
@Header(name: "Content-Type") var contentType = "application/json"The name is the name of the header, and the value must conform the CustomStringConvertible protocol.
func getItem(id: Int) async throws -> Item {
let client = ... // see below
let baseUrl = "https://example.com"
let retroSwift = RetroSwift(client: client)
@Path(path: "/api/v1/items/{id}", name: "id") var path = id
@Query(name: "fields") var fields = "id,title"
@Query(name: "limit") var fields = 100
@GET(baseURL: baseUrl, path: path, queries: [fields]) var request
return try await retroSwift.execute(request: request)
}This will generate following request:
HTTP GET https://example.com/api/v1/items/14572?fields=id,title&limit=100
Supported methods:
| HTTP Method | Signature |
|---|---|
| GET | @GET(...) |
| PUT | @PUT(...) |
| POST | @POST(...) |
| DELETE | @DELETE(...) |
| OPTIONS | coming soon |
| TRACE | coming soon |
| PATCH | coming soon |
| CONNECT | coming soon |
| HEAD | coming soon |
You need to provide a HTTP client to RetroSwift.
This client must implement the HTTPClient protocol:
protocol HTTPClient {
func execute<T: Decodable>(request: URLRequest) async throws -> T
}It's recommended to use OkHTTPClient as the networking client.
- Add dynamic parameter list to
@Path. - Add
Datainit to@Body. - Improve documentation
- Improve unit test coverage.
We always appreciate contributions from the community. Please make sure to cover your changes with unit tests.
Inspired by Retrofit.