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 optionalGeneric networking library written using Swift async/await
Socket Swift async/await based socket library Introduction This library exposes an idiomatic Swift API for interacting with POSIX sockets via an async
iOS 15, MVVM, Async Await, Core Data, Abstract Network Layer, Repository & DAO design patterns, SwiftUI and Combine
Making HTTP API requests in Swift using Foundation can be verbose and use a mix of types like URL, URLComponents and URLRequest to form a request and then handling all the encoding and decoding steps later
This generic SOAP client allows you to access web services using a your iOS app, Mac OS X app and Apple TV app. With this Framework you can create iPh
Postie - The Next-Level HTTP API Client using Combine Postie is a pure Swift library for building URLRequests using property wrappers.
Area51 Area51 is an open source Reddit client for iOS built entirely in Swift! Get the public beta on TestFlight Join the public Slack channel to coll
Project 3 - Twitter Client Name of your app is a basic twitter app to read your
A native, lightweight and secure time-based (TOTP) & counter-based (HOTP) password client built for iOS Built by Tijme Gommers – Buy me a coffee via P
Embassy Super lightweight async HTTP server in pure Swift. Please read: Embedded web server for iOS UI testing. See also: Our lightweight web framewor
CityWiseAQI This app is using web-socket for realtime updation of aqi for dedicated inidan cities. We're following MVVM architecture in this app. This
Version 1.0.10 Currently Available Platform Version iOS 12.0 tvOS 10.0 macOS 10.15 watchOS 3.0 macCatalyst 13.0 Hover is a Network layer which uses Ap
An unofficial supported Swift client library for accessing News API.
WANetworkRouting Developed and Maintained by ipodishima Founder & CTO at Wasappli Inc. Sponsored by Wisembly A routing library to fetch objects from a
api.video iOS client api.video is the video infrastructure for product builders.
OTFCloudClientAPI TheraForge's Client REST API Framework to Connect to TheraForg
TMDB Client App Instructions Instructions for project setup. 1. Clone the project. 2. Go to "TMDB Client App" folder location on terminal and enter "p
Documentation <h5 align="right"><a href="http://demo.swiftexpress.io/">Live ?? server running Demo <img src="https://cdn0.iconfinder.com/data/icons/
Conduit Conduit is a session-based Swift HTTP networking and auth library. Within each session, requests are sent through a serial pipeline before bei
7 Aug 3, 2022
89 Dec 29, 2022
18 Dec 23, 2022
13 Nov 5, 2022
479 Nov 22, 2022
28 Jul 23, 2022
141 Dec 26, 2022
0 Feb 7, 2022
770 Jan 8, 2023
540 Dec 15, 2022
2 Feb 7, 2022
124 Oct 23, 2022
9 Oct 1, 2022
10 Nov 20, 2022
8 Dec 2, 2022
0 Dec 23, 2021
0 Dec 26, 2021
850 Dec 2, 2022
52 Oct 26, 2022