SwiftyRequest is an HTTP client built for Swift.
The latest release of SwiftyRequest is built upon the Swift-NIO based async-http-client.
- Features
- Installation
- Usage
- CircuitBreaker Integration
- Response Methods
- Migrating from SwiftyRequest v2 to v3
- Several response methods (e.g. Data, Object, Array, String, etc.) to eliminate boilerplate code in your application.
- Direct retrieval of
Codabletypes. - JSON encoding and decoding.
- Integration with the CircuitBreaker library.
- Authentication tokens.
- Client Certificate support (2-way SSL).
- Multipart form data.
The latest version of SwiftyRequest requires Swift 5 or later.
Swift 4 support is available in the 2.x release of SwiftyRequest.
To leverage the SwiftyRequest package in your Swift application, you should specify a dependency for it in your Package.swift file:
Add SwiftyRequest to the dependencies within your application's Package.swift file. Substitute "x.x.x" with the latest SwiftyRequest release.
.package(url: "https://github.com/IBM-Swift/SwiftyRequest.git", from: "x.x.x")Add SwiftyRequest to your target's dependencies:
.target(name: "example", dependencies: ["SwiftyRequest"]),To make outbound HTTP calls using SwiftyRequest, create a RestRequest instance. The method parameter is optional (it defaults to .get), the url parameter is required.
Example usage of RestRequest:
import SwiftyRequest
let request = RestRequest(method: .get, url: "http://myApiCall/hello")
request.credentials = .basicAuthentication(username: "John", password: "12345")You can customize the following parameters in the HTTP request:
headerParameters: The HTTP header fields which form the header section of the request message.credentials: The HTTP authentication credentials for the request.acceptType: The HTTPAcceptheader, defaults toapplication/json.messageBody: The HTTP message body of the request.productInfo: The HTTPUser-Agentheader.circuitParameters: ACircuitParametersobject which includes a reference to a fallback function that will be invoked when the circuit is failing fast (see CircuitBreaker Integration).contentType: The HTTPContent-Type header, defaults toapplication/json.method: The HTTP method specified in the request, defaults to.GET.queryItems: Any query parameters to be appended to the URL.
The result object we get back is of type Result<RestResponse<String>, Error> so we can perform a switch to determine if the network call was successful:
request.responseString { result in
switch result {
case .success(let response):
print("Success")
case .failure(let error):
print("Failure")
}
}URLs can be templated with the {keyName} syntax, allowing a single RestRequest instance to be reused with different parameters.
In this example, we invoke a response method with two template parameters to be used to replace the {state} and {city} values in the URL:
let request = RestRequest(url: "http://api.weather.com/api/123456/conditions/q/{state}/{city}.json")
request.responseData(templateParams: ["state": "TX", "city": "Austin"]) { result in
// Handle response
}In this example, we invoke a response method with a query parameter to be appended onto the url behind the scenes so that the RestRequest gets executed with the following url: http://api.weather.com/api/123456/conditions/q/CA/San_Francisco.json?hour=9. Any query items already specified in the request URL will be replaced:
let request = RestRequest(url: "http://api.weather.com/api/123456/conditions/q/CA/San_Francisco.json")
request.responseData(queryItems: [URLQueryItem(name: "hour", value: "9")]) { result in
// Handle response
}SwiftyRequest has built-in functionality for leveraging the CircuitBreaker library to increase your application's stability. To make use of this functionality, assign a CircuitParameters object to the circuitParameters property. This object will include a reference to a fallback function that will be invoked when the circuit is failing fast.
Here is an example of a fallback closure:
let breakerFallback = { (error: BreakerError, msg: String) in
print("Fallback closure invoked... circuit must be open.")
}We initialize the CircuitParameters object and create a RestRequest instance. The only required value you need to set for CircuitParameters is the fallback (everything else has default values).
let circuitParameters = CircuitParameters(timeout: 2000,
maxFailures: 2,
fallback: breakerFallback)
let request = RestRequest(method: .GET, url: "http://myApiCall/hello")
request.circuitParameters = circuitParametersAt this point, you can use any of the response methods mentioned in the section below.
RestRequest provides a number of response functions that call back with a Result containing either a response or an error.
To invoke the request and receive a response, you can use the response function. The completion handler will be called back with a result of type Result<HTTPClient.Response, Error>.
RestRequest provides additional convenience methods you can use based on the type of the response body you expect:
responseDatarequires that the response contains a body, and calls back with aResult<RestResponse<Data>, Error>.responseObject<T: Decodable>decodes the response body to the specified type, and calls back with aResult<RestResponse<T>, Error>.responseStringdecodes the response body to a String, and calls back with aResult<RestResponse<String>, Error>.responseDictionarydecodes the response body as JSON, and calls back with aResult<RestResponse<[String: Any]>, Error>.responseArraydecodes the response body as a a JSON array, and calls back with aResult<RestResponse<[Any]>, Error>.responseVoiddoes not expect a response body, and calls back with aResult<HTTPClient.Response, Error>.
let request = RestRequest(method: .get, url: "http://localhost:8080/users/{userid}")
request.responseObject(templateParams: ["userid": "1"]) { (result: Result<RestResponse<User>, RestError>) in
switch result {
case .success(let response):
let user = response.body
print("Successfully retrieved user \(user.name)")
case .failure(let error):
if let response = error.response {
print("Request failed with status: \(response.status)")
}
if let responseData = error.responseData {
// Handle error response body
}
}
}There are a number of changes to the API in SwiftyRequest v3 compared to the v2 release:
- The
RestRequestinitializer parametercontainsSelfSignedCerthas been renamedinsecureto better reflect its purpose (turning off SSL certificate verification). The old name has been deprecated and may be removed in a future release. - The
completionHandlercallback ofresponseData(et al) has changed from(RestResponse<Data>) -> Voidto(Result<RestResponse<Data>, RestError>) -> Void. - The
JSONDecodableandJSONEncodabletypes have been removed in favour of usingCodabledirectly. TheresponseObjectfunction allows you to receive a Codable object in a response. - Convenience functions for handling raw JSON have been added.
responseDictionaryandresponseArrayalow retrieval of JSON as[String: Any]and[Any]respectively, and sending of raw JSON can be performed by setting therequest.messageBodyDictionaryorrequest.messageBodyArrayproperties. - the
RestErrortype is now returned explicitly in the.failurecase. If the error pertains to a response with a non-success status code, you can access the response witherror.response. If the response also contained body data, it can be retrieved viaerror.responseData.
Specify a ClientCertificate when creating a RestRequest to enable a client certificate to be presented upon a secure request (2-way SSL).
The certificate may be provided in PEM format - either from a file, a string or Data, and an optional passphrase. The PEM data should contain the certificate and its corresponding private key. If the private key is encrypted, the corresponding passphrase should be specified when constructing the ClientCertificate.
If you need to handle certificates in other formats, you may create a ClientCertificate directly from a NIOSSLCertificate and NIOSSLPrivateKey. For more information on these types, see the documentation for the async-http-client project.
For more information visit our API reference.
We love to talk server-side Swift, and Kitura. Join our Slack to meet the team!
This library is licensed under Apache 2.0. Full license text is available in LICENSE.