Thunder Request
Thunder Request is a Framework used to simplify making http and https web requests.
Installation
Setting up your app to use ThunderBasics is a simple and quick process. You can choose between a manual installation, or use Carthage.
Carthage
- Add
github "3sidedcube/ThunderRequest" == 2.3.1to your Cartfile. - Run
carthage update --platform iosto fetch the framework. - Drag
ThunderRequestinto your project's Linked Frameworks and Libraries section from theCarthage/Buildfolder. - Add the Build Phases script step as defined here.
Manual
- Clone as a submodule, or download this repo
- Import ThunderRequest.xcproject into your project
- Add ThunderRequest.framework to your Embedded Binaries.
- Wherever you want to use ThunderBasics use
import ThunderRequestif you're using swift.
Authentication Support
Support for authentication protocols such as OAuth2 is available via the Authenticator protocol which when set on RequestController will have it's delegate methods called to refresh the user's token when it either expires or a 403 is sent by the server.
When authenticator is set on RequestController any current credentials will be pulled from the user's keychain by the service identifier provided by authIdentifier on the protocol object.
To register a credential for the first time to the user's keychain, use the method set(sharedRequestCredentials:savingToKeychain:) after having set the delegate. This will store the credential to the keychain for later use by the request controller and also set the sharedRequestCredential property on the request controller.
If the request controller detects that the RequestCredential object is expired, or receives a 403 on a request it will call the method reAuthenticate(credential:completion:) to re-authenticate the user before then continuing to make the request (Or re-making) the request.
Examples
All of the examples shown below are shown with all optional parameters excluded, for example the request, download and upload functions have multiple parameters (For things such as header overrides and base url overrides) as outlined in the generated docs.
Initialization
guard let baseURL = URL(string: "https://httpbin.org/") else {
fatalError("Unexpectedly failed to create URL")
}
let requestController = RequestController(baseURL: baseURL)
GET request
requestController.request("get", method: .GET) { (response, error) in
// Do something with response
}
POST request
let body = [
"name": "Thunder Request",
"isAwesome": true
]
requestController.request("post", method: .POST, body: JSONRequestBody(body)) { (response, error) in
// Do something with response
}
Request bodies
The body sent to the request function must conform to the RequestBody protocol. There are multiple extensions and structs built into the project that conform to this protocol for ease of use.
JSONRequestBody
Formats the request as JSON, and sets the request's Content-Type header to application/json.
let bodyJSON = [
"name": "Thunder Request",
"isAwesome": true
]
let body = JSONRequestBody(bodyJSON)
PropertyListRequestBody
Similar to JSONRequestBody but uses the "text/x-xml-plist" or "application/x-plist" Content-Type.
let bodyPlist = [
"name": "Thunder Request",
"isAwesome": true
]
let body = PropertyListRequestBody(bodyPlist, format: .xml)
MultipartFormRequestBody
Formats a dictionary of objects conforming to MultipartFormElement to the data required for the multipart/form-data; boundary= Content-Type.
let multipartElements = [
"name": "Thunder Request",
"avatar": MultipartFormFile(
image: image,
format: .png,
fileName: "image.png",
name: "image"
)!
]
let body = MultipartFormRequestBody(
parts: multipartElements,
boundary: "----SomeBoundary"
)
FormURLEncodedRequestBody
Similar to JSONRequestBody except uses the "application/x-www-form-urlencoded" Content-Type and formats the payload to be correct for this type of request.
let bodyJSON = [
"name": "Thunder Request",
"isAwesome": true
]
let body = FormURLEncodedRequestBody(bodyJSON)
ImageRequestBody
Converts a UIImage to a request payload data and Content-Type based on the provided format.
let imageBody = ImageRequestBody(image: image, format: .png)
EncodableRequestBody
Converts an object which conforms to the Encodable (Or Codable) protocol to either JSON or Plist based on the format provided upon initialisation (Defaults to JSON).
let someEncodableObject: CodableStruct = CodableStruct(
name: "Thunder Request",
isAwesome: true
)
let body = EncodableRequestBody(someEncodableObject)
Request Response
The request response callback sends both an Error? object and a RequestResponse? object. RequestResponse has helper methods for converting the response to various Swift types:
Decodable
If your object conforms to the Decodable (Or Codable) is can be decoded directly for you:
let codableArray: [CodableStruct]? = response.decoded()
let codableObject: CodableStruct? = response.decoded()
Dictionary
let dictionaryResponse = response.dictionary
Array
let arrayResponse = response.array
String
let stringResponse = response.string
let utf16Response = response.string(encoding: .utf16)
The RequestResponse object also includes the HTTP status as an enum, the raw Data from the request response, the original response (For when a request was re-directed), and the request headers (headers)
Downloading
Downloading from a url is as simple as making any a request using any other HTTP method
let requestBaseURL = URL(string: "https://via.placeholder.com/")!
let requestController = RequestController(baseURL: requestBaseURL)
requestController.download("500", progress: nil) { (response, url, error) in
// Do something with the filePath that the file was downloaded to
}
Uploading
Uploading is just as simple, and can be done using any of the RequestBody types listed above, as well as via a raw Data instance or from a file URL
requestController.uploadFile(fileURL, to: "post", progress: { (progress, totalBytes, uploadedBytes) in
// Do something with progress
}) { (response, _, error) in
// Do something with response/error
}
Building Binaries for Carthage
Since Xcode 12 there has been issues with building Carthage binaries caused by the inclusion of a secondary arm64 slice in the generated binary needed for Apple Silicon on macOS. This means that rather than simply using carthage build --archive you need to use the ./carthage-build build --archive command which uses the script included with this repo. For more information, see the issue on Carthage's github here
We will be investigating moving over to use SPM as an agency soon, and will also look into migrating to use .xcframeworks as soon as Carthage have support for it.
Code level documentation
Documentation is available for the entire library in AppleDoc format. This is available in the framework itself or in the Hosted Version
License
See LICENSE.md
33.3k Jan 5, 2023
2 Mar 20, 2022
30 Nov 19, 2022
67 Dec 5, 2022
60 Sep 15, 2022
3.7k Dec 28, 2022
12.3k Jan 8, 2023
369 Nov 14, 2022
386 Sep 1, 2022
845 Oct 30, 2022
410 Dec 30, 2022
18 Feb 25, 2018
0 Nov 11, 2021
10 Jan 29, 2022
29 Nov 4, 2022
7 Aug 3, 2022
4 Oct 17, 2022
7 Nov 19, 2022
316 Oct 6, 2022