A modern web API client in Swift built using Async/Await and Actors.
let client = APIClient(host: "api.github.com")
// Using the client directly
let user: User = try await client.send(.get("/user"))
try await client.send(.post("/user/emails", body: ["[email protected]"]))
// Using a predefined API definition
let repos = try await client.send(Resources.users("kean").repos.get)
For more information, read Web API Client in Swift.
Tests pass locally. Of course, the alternative is that we could just @preconcurrency import Get, but.. going to need proper support anyway and the locking mechanisms fix potential data races that exist today.
Hi 👋🏻
When declaring a method with an optional response body (see example), the call only results in a decoding error because the method tries to decode an empty response.
Optional response body method:
func getWatching(slug: String, extended info: ExtendedInfo?) async throws -> Response<Users.GetWatching.Response?>
Error:
dataCorrupted(Swift.DecodingError.Context(
codingPath: [],
debugDescription: "The given data was not valid JSON.",
underlyingError: Optional(Error Domain=NSCocoaErrorDomain Code=3840 "Unable to parse empty data." UserInfo={NSDebugDescription=Unable to parse empty data.})
)
)
The same code worked in previous version though (it simply returned nil).
Original issue with proposal:
APIInterface name is open for a great improvement. I'm not too familiar with Swift on linux so I don't know if the OS check is appropriate, but included anyway.
Line #43 of APIClient has this:
public func send(_ request: URLRequest) async throws -> (Data, URLResponse) {
do {
return try await actuallySend(request)
} catch {
guard await delegate.shouldClientRetry(self, withError: error) else { throw error }
return try await actuallySend(request)
}
}
Perhaps I'm mistaken, but a 401/403 doesn't actually throw an error here, it'll just continue a normal right? The shouldClientRetry would only be called if the network had some actually throwing error here, right?
I usually approach OAuth in a completely different way, and if you agree I'd love to submit a PR with a different approach where auth'ed endpoints are wrapped at the call site, rather than handled inside of the API framework.
As there are no dependencies on iOS SDK, enabled other Apple platforms. In theory, with custom implementation of URLSession.data(for:) it could be ported to previous OS versions (requires Xcode 13.2) and Linux.
Unfortunately, seems that custom URLProtocol doesn't properly works with POST requests on watchOS and Mocker doesn't have any non-iOS tests to re-verify. All other tests work on all platforms.
Hello @kean. Thank you for this library, I really admire the elegant API you achieved with this.
I've been using Get in a side project and stumbled into an issue where an explicitly written + character was not encoded when used in a query string (e.g. domain.tld?query=value1+value2). This resulted in an unexpected response from the API i was using.
According to a note in this Apple Doc which also refers to RFC 3986 and W3C, the + sign is a valid character for representing a space in a query string. Due to this fact it seems, the character is not automatically encoded when reading the url from a URLComponents instance. The same note suggests to preemptively encode the + character as well if needed.
I think it would be reasonable to add this behavior to Get, what are your thoughts?
I made a sample implementation in a fork here. Heavily inspired by Alamofire.
featureTired out calling the GitHubAPI usage with updating GitHubAPIClientDelegete with my personal Github token but getting a 401 unauthorized.
try await usage()
I don't think the GitHubAPIClientDelegete is adding the required requests headers.
Brian
In the signature of the delegate method
func shouldClientRetry(_ client: APIClient, withError error: Error) async throws -> Bool
might be useful to add URLRequest.
This could be useful for handling situations where multiple requests fail.
Or can you please show an example or hint how you handle this situation?
Hello :)
I've created a proposal for an additional feature and would appreciate your feedback.
Provides an implementation of APIClientDelegate specifically for authenticating requests.
Alamofire provides an implementation called AuthenticationInterceptor for authentication. (docs)
AuthenticationInterceptor takes care of state management when sending concurrent requests.
Therefore, users only need to implement each type that conforms to the AuthenticationCredential protocol and the Authenticator protocol.
I would like to see an implementation of AuthenticationInterceptor that manages authentication in Get as well.
(With an implementation based on async/await and actor, of course.)
AuthenticatorTypes adopting the Authenticator protocol will load or update Credential and apply the Credential to URLRequest.
AuthenticationInterceptorThe AuthenticationInterceptor class provides authentication for requests using exclusive control. It relies on an Authenticator type to handle the actual URLRequest authentication and Credential refresh.
AuthenticationInterceptor uses actor State, for exclusion control, and can apply and refresh authentication in order even for parallel requests.
Authenticator protocol.public class SampleAuthenticator: Authenticator {
public typealias Credential = Token
public var tokenStore: TokenStore
public let client: APIClient
public init(tokenStore: TokenStore, clientToRefreshCredential: APIClient) {
self.tokenStore = tokenStore
self.client = clientToRefreshCredential
}
public func credential() async throws -> Token {
if let token = tokenStore.token, token.expiresDate < Date() {
return token
}
// If there is no token, generate a token.
let token: Token = try await client.send(.post("/token")).value
tokenStore.save(token)
return token
}
public func apply(_ credential: Token, to request: inout URLRequest) async throws {
request.setValue(authorizationHeaderValue(for: credential), forHTTPHeaderField: "Authorization")
}
public func refresh(_ credential: Credential) async throws -> Credential {
let token: Token = try await client.send(.put("/token", body: ["refresh_token": credential.refreshToken])).value
tokenStore.save(token)
return token
}
public func didRequest(_: URLRequest, failDueToAuthenticationError error: Error) -> Bool {
if case .unacceptableStatusCode(let status) = (error as? APIError), status == 401 {
return true
}
return false
}
public func isRequest(_ request: URLRequest, authenticatedWith credential: Token) -> Bool {
request.value(forHTTPHeaderField: "Authorization") == authorizationHeaderValue(for: credential)
}
private func authorizationHeaderValue(for token: Token) -> String {
"token \(token.accessToken)"
}
}
AuthenticationInterceptor with SampleAuthenticator as APIClientDelegatelet authenticator = SampleAuthenticator(tokenStore: TokenStore(),
clientToRefreshCredential: APIClient(host: "example.com"))
let apiClient = APIClient(host: "example.com") {
$0.delegate = AuthenticationInterceptor(authenticator: authenticator)
}
Changed method shouldClientRetry(_ client: APIClient, withError error: Error) async throws -> Bool to shouldClientRetry(_ client: APIClient, for request: URLRequest, with error: Error) async throws -> Bool in APIClientDelegate because URLRequest was needed to manage retries for parallel requests.
In order to pass the URLRequest actually sent to APIClientDelegate.shouldClientRetry(_:for:with:), APIClientDelegate.client(_:willSendRequest:) is now called from APIClient.send(_:) to call it from APIClient.send(_:) instead of APIClient.actuallySend(_:).
👋
While working on CreateAPI/CreateAPI#83, I noticed that Xcode 13.2 tests failed because Get 1.0.0 bumped the Swift requirement up to 5.6. While I am not opposed to dropping support for older versions of Xcode, I don't want to do it if there isn't a good reason to.
I was going to tag you on the CreateAPI Pull Request, but I first wanted to check if the project still compiled using Xcode 13.2 since I didn't see any surrounding commits/discussion, and at this point, I thought it was just easier to raise a PR here instead 😄
Anyway, my question is: Does Get need to drop support for Swift 5.5 just yet? Even if we got at least one tagged release under 1.0.0, this would allow CreateAPI to require both Get 1.0.0 while still supporting Swift 5.5.
If you are happy to keep it, I've included in this PR some updates to the CI checks to make sure that we test Swift 5.5 on both macOS and Linux. But equally, if there is a reason not to revert the change then I think I can just do the same over in CreateAPI as well.
If you do merge this PR, would it be possible to tag a release over the next few days to unblock me?
Thanks again!
I'm considering redesigning the APIClient public API for Get 1.0. It was initially designed to accommodate only the most basic scenarios, but I'd like it to be more flexible. Here is a draft of a new API.
public protocol APIClient2 {
// No changes in these APIs, except for removal of magic `Response<Data>` and `Response<String>` support (see p3)
func send<T: Decodable>(_ request: Request<T>) async throws -> Response<T>
func send<T: Decodable>(_ request: Request<T?>) async throws -> Response<T?>
@discardableResult func send(_ request: Request<Void>) async throws -> Response<Void>
// Getting decoded response for `URL`/`URLRequest`
func value<T: Decodable>(_ type: T.Type, for url: URL) async throws -> Response<T>
func value<T: Decodable>(_ type: T.Type, for urlRequest: URLRequest) async throws -> Response<T>
// Getting raw response `Data` (no decoding)
func data(for url: URL) async throws -> Response<Data>
func data(for urlRequest: URLRequest) async throws -> Response<Data>
func data<T>(for request: Request<T>) async throws -> Response<Data>
// Getting response `String` (no decoding except for .utf8 decoding)
func string(for url: URL) async throws -> Response<String>
func string(for urlRequest: URLRequest) async throws -> Response<String>
func string<T>(for request: Request<T>) async throws -> Response<String>
// (?) Add `URLSessionDataDelegate` to all APIs too for pogress reporting, etc.
func response<T: Decodable>(for request: Request<T>, delegate: URLSessionDataDelegate) async throws -> Response<T>
}
Main Changes
URL and URLRequest in addition to RequestURLSessionDataDelegate for progress reporting, per-task auth, etc.Response<Data> and Response<String> support from send(_:). If you use send(_:), they'll just use the default Decodable implementation for these types. You'll need to call data(for:) or string(for:) instead – faster, more discoverable, self-documentingOur api server gives a 422 response when validating request params:
{
"errors": [{ "detail": "Missing field: anon_id" }]
}
However, Get only supplies the error code: Response status code was unacceptable: 422 via APIError
.unacceptableStatusCode(let statusCode)
How can we hook into the actual error response for logging and (sometimes) showing to the user?
featurewithResponse always setting method to .get - #62, thanks to @briancordanyoungImportant fix for iOS 16
DataLoader with the new iOS 16 didCreateTask delegate methodImportant fix for iOS 16
DataLoader with the new iOS 16 didCreateTask delegate methodnil - #58, thanks to @PomanksFull Changelog: https://github.com/kean/Get/compare/2.0.1...2.1.0
Source code(tar.gz)This release is a quick follow-up to Get 1.0 that fixes some of the shortcomings of the original Request type design.
Request can now be initialized with either a string (path: String) or a URL (url: URL).get(...), .post(...), and other factory methods with a single HTTPMethod type. Example: Request(path: "/user", method: .patch)Request initializer is now path or url, not method that has a default valueRequest initializer that defaults to the Void response type unless you specify it explicitlybody property of Request writableupload(for:data:) method - #50, thanks to @soemarkoAPIDelegate client(_:makeURLFor:query:) method with client(_:makeURLForRequest:) so that you have complete access to the RequestSource code(tar.gz)See #51 for the reasoning behind the
Requestchanges
This release is a quick follow-up to Get 1.0 that fixes some of the shortcomings of the original design of the Request type.
Request can now be initialized with either a string (path: String) or a URL (url: URL).get(...), .post(...), and other factory methods with a single HTTPMethod type. Example: Request(path: "/user", method: .patch)Request initializer is now path or url, not method that has a default valueRequest initializer that defaults to the Void response type unless you specify it explicitlybody property of Request writableupload(for:data:) method - #50, thanks to @soemarkoAPIDelegate client(_:makeURLFor:query:) method with client(_:makeURLForRequest:) so that you have complete access to the RequestSource code(tar.gz)See #51 for the reasoning behind the
Requestchanges
Full Changelog: https://github.com/kean/Get/compare/1.0.1...1.0.2
Source code(tar.gz)@discardableResult to all upload() and send() methodsGet 1.0 is a big release that brings it on par with Moya+Alamofire while still keeping its API surface small and focused. This release also includes new reworked documentation generated using DocC, and many other improvements.
The first major change is the addition of two new parameters the existing send method: delegate and configure:
public func send<T: Decodable>(
_ request: Request<T>,
delegate: URLSessionDataDelegate? = nil,
configure: ((inout URLRequest) -> Void)? = nil
) async throws -> Response<T>
With delegate, you can modify the behavior of the underlying task, monitor the progress, etc. And with the new configure closure, you get access to the entire URLRequest API:
let user = try await client.send(.get("/user")) {
$0.cachePolicy = .reloadIgnoringLocalCacheData
}
The second major change is the addition of new methods: upload(...) for uploading data from a file and download(...) for downloading data to a file.
let response = try await client.download(for: .get("/user"))
let fileURL = response.location
try await client.upload(for: .post("/avatar"), fromFile: fileURL)
delegate parameter to send() method that sets task-specific URLSessionDataDelegate - #38configure parameter to send() method that allows configuring URLRequest before it is sentdownload(for:delegate:configure:) method - #40upload(for:withFile:delegate:configure:) methodclient(_:shouldRetryRequest:attempts:error:) delegate method (the method with an old signature is deprecated)client(_:validateResponse:data:request:) to APIClientDelegate that allows to customize validation logicclient(_:makeURLForRequest:) method to APIClientDelegate to address #35task, originalRequest, currentRequest to ResponseAPIClient/makeURLRequest(for:) method to the client in case you need to create URLRequest without initiating the downloadContent-Type and Accept headers using session httpAdditionalHeaders and Request headersRequest factory methods that default to Void as a response type and streamline the existing methodswithResponse(_:) to allow changing request's response typesessionDelegateQueue parameter to APIClient.ConfigurationsessionDelegate from APIClient.Configuration on Linuxconfiguration and session properties to APIClientRequest/path to Request/url making it clear that absolute URLs are also supportedTask.detached instead of using a separate actor for serialization"/" not being appended to the baseURLperformWithRetries so its failure won't trigger shouldRetrywillSendRequest throwing an errorid to Request initbody property to Request and remove deprecated pathsend() -> Response<T?> variantGet 1.0 is a big release that brings it on par with Moya+Alamofire while still keeping its API surface small and focused. This release also includes new reworked documentation generated using DocC, and many other improvements.
The first major change is the addition of two new parameters the existing send method: delegate and configure:
public func send<T: Decodable>(
_ request: Request<T>,
delegate: URLSessionDataDelegate? = nil,
configure: ((inout URLRequest) -> Void)? = nil
) async throws -> Response<T>
With delegate, you can modify the behavior of the underlying task, monitor the progress, etc. And with the new configure closure, you get access to the entire URLRequest API:
let user = try await client.send(.get("/user")) {
$0.cachePolicy = .reloadIgnoringLocalCacheData
}
The second major change is the addition of new methods: upload(...) for uploading data from a file and download(...) for downloading data to a file.
let response = try await client.download(for: .get("/user"))
let fileURL = response.location
try await client.upload(for: .post("/avatar"), fromFile: fileURL)
delegate parameter to send() method that sets task-specific URLSessionDataDelegate - #38configure parameter to send() method that allows configuring URLRequest before it is sentdownload(for:delegate:configure:) method - #40upload(for:withFile:delegate:configure:) methodclient(_:shouldRetryRequest:attempts:error:) delegate method (the method with an old signature is deprecated)client(_:validateResponse:data:request:) to APIClientDelegate that allows to customize validation logicclient(_:makeURLForRequest:) method to APIClientDelegate to address #35task, originalRequest, currentRequest to ResponseAPIClient/makeURLRequest(for:) method to the client in case you need to create URLRequest without initiating the downloadContent-Type and Accept headers using session httpAdditionalHeaders and Request headersRequest factory methods that default to Void as a response type and streamline the existing methodswithResponse(_:) to allow changing request's response typesessionDelegateQueue parameter to APIClient.ConfigurationsessionDelegate from APIClient.Configuration on Linuxconfiguration and session properties to APIClientRequest/path to Request/url making it clear that absolute URLs are also supportedTask.detached instead of using a separate actor for serialization"/" not being appended to the baseURLGet 1.0 beefs up the existing APIs by providing access to most of the underlying URLSession APIs. This release also includes new documentation generated using DocC.
The main send method now has two more options: delegate and configure:
public func send<T: Decodable>(
_ request: Request<T>,
delegate: URLSessionDataDelegate? = nil,
configure: ((inout URLRequest) -> Void)? = nil
) async throws -> Response<T>
Usage:
let user = try await client.send(.get("/user")) {
$0.cachePolicy = .reloadIgnoringLocalCacheData
}
delegate parameter to send() method that sets task-specific URLSessionDataDelegate - #38configure parameter to send() method that allows configuring URLRequest before its sentdownload(for:delegate:configure) method - #40client(_:shouldRetryRequest:attempts:error:) delegate methodclient(_:makeURLForRequest:) method to the client delegate to #35sessionDelegateQueue parameter to APIClient.ConfigurationsessionDelegate from APIClient.Configuration on Linux"/" not being appended to the baseURLTask.detached instead of using a separate actor for serializationRequest and Response conditionally Sendable (requires Xcode 13.3)URLRequest cURLDescription() extension – it was never meant to be in the scope? when creating the request with empty query items - #29, thanks to Guilherme SouzabaseURL client configuration option. Deprecate host, port, and isInsercure.Usage:
APIClient(baseURL: URL(string: "https://api.github.com"))
URLRequest parameter to shouldClientRetry(_:request:withError:) in APIClientDelegate - #23, thanks to Pavel KrusekAPIClientDelegate method throwable - #16, thanks to Tomoya HayakawaRequest intializersend() variant now also supports String, and Data.send variant that works with optional types. If the response is empty – return nil.value(for:). Use send(...).value, which is exactly the same amount of code.willSend async - #11, thanks to Lars-Jørgen KristiansenAPIClient (same as ImagePipeline in Nuke):let client = APIClient(host: "api.github.com") {
$0.delegate = MyClientDelegate()
$0.sessionConfiguration.httpAdditionalHeaders = ["apiKey": "easilyExtractableSecretKey"]
}
URLSessionDelegate) when instantiating a client for monitoring URLSession events – the client will continue doing its thingURLSessionTaskMetrics) to ResponseResponse initializer and make properties writablesend now supports fetching Response<Data> (returns raw data) and Response<String> (returns plain text)(String, String?) tuples enabling "explode" supportheaders in the requestpost, put, and patch can now be emptybody parameter to delete methodbody parameter optionalHackerNewsReader This was built during my bootcamp using SwiftUI, WebKit and an API from Hacker News. This was programmed from scratch with SwiftUI. I
Outline Client The Outline Client is a cross-platform VPN or proxy client for Windows, macOS, iOS, Android, and ChromeOS. The Outline Client is design
AQI - Assignment This is an iOS App which shows live AQI (Air quality index) dat
A repository that demonstrates the difficulty to run async tests with Xcode 13.2 beta on pre iOS-15 simulators This demonstration uses an iOS 13.7 sim
An IPFS client/api Swift Package, with the ability to add and pin any data on iOS/iPadOS/macOS. Originally bundled with GraniteUI, pulled out for independant use by any party.
Pexels-Swift Pexels.com API client library for the Swift programming language. Overview This Swift Package is a wrapper for Pexels API to get access t
Tofu A simple Todo app built with SwiftUI, a REST API, and a local Realm cache.
Introduction Respresso is a centralized resource manager for shared Android, iOS and Web frontend projects. It allows you to simply import the latest
We would like to create a web application in JavaScript/VSCode with Google Firebase as the database. We want to make a Pokemon team creator
Runtime Mobile Security (RMS) ?? ?? by @mobilesecurity_ Runtime Mobile Security (RMS), powered by FRIDA, is a powerful web interface that helps you to
A movie api created using Vapor, Fluent (ORM) and Postgres
Google Blogger iOS App Using Google Blogger API to build an iOS app like Medium！
Swift Tutorials This is not a package, it's just a bunch of tutorials This project uses Apple's DocC (Documentation Compiler) to create a set of Swift
Food Recipes Application This is my first IOS App. The first page is sign in and sign up page. I controll informations with regex in sign up page. If
CurrencyConverter Stack: Xcode 12.5.1 iOS 14.5 UIkit iOS deployment target: 13.0
AuroraEditor AuroraEditor is a IDE built by the community, for the community, and written in Swift for the best native performance and feel for macOS.
Delta Plugin Template This repository is a template for Delta Client plugins. To create a plugin, create a repo from this template repo and then repla
A simple Hacker News mobile client. Overview This app was built with the Hacker News API This is one of my first apps outside of a tut
Discord Lite An ultra-lightweight native Discord client for vintage and modern Mac OS Minimum System Requirements Mac OS X version 10.4 (Tiger) PowerP
2 Feb 25, 2022
7.3k Dec 31, 2022
3 Jul 21, 2022
0 Nov 1, 2021
4 Dec 8, 2022
4 Sep 1, 2022
1 Feb 23, 2022
10 Nov 8, 2022
1 Aug 4, 2022
2k Dec 29, 2022
0 Jan 10, 2022
9 Dec 13, 2022
11 Aug 9, 2022
1 Dec 17, 2021
2 Sep 4, 2022
704 Jan 8, 2023
1 Jan 12, 2022
0 Nov 29, 2021
155 Jan 2, 2023