AlamoRecord is a powerful yet simple framework that eliminates the often complex networking layer that exists between your networking framework and your application. AlamoRecord uses the power of Alamofire and the concepts behind the ActiveRecord pattern to create a networking layer that makes interacting with your API easier than ever.
- iOS 10.0+ / macOS 10.12+ / tvOS 10.0+ / watchOS 3.0+
- Xcode 10.2+
- Swift 5.1
AlamoRecord is available through CocoaPods. To install it, simply add the following line to your Podfile:
pod 'AlamoRecord'The power of AlamoRecord lies within four main components.
These are data objects that are retrieved from an API. All data objects that inherit from this class automatically receive built in helpers such as create, find, update, and destroy. This is also known as CRUD.
These are the work horses of AlamoRecord. They contain all of the networking helpers that AlamoRecord needs in order to create your application's networking layer. They are responsible for each request that your AlamoRecordObject's make. They also contain upload and download helpers.
These store all of the information needed in order to make a proper request through instances of RequestManager's.
These are errors that are returned from an API. On a failed request, the JSON returned will be mapped from the predefined fields that are setup.
Let's assume we are developing an application that allows user's to interact with each other via posts.
We first need to create a class that conforms to AlamoRecordURL. Let's name it ApplicationURL:
class ApplicationURL: AlamoRecordURL {
var absolute: String {
return "https://jsonplaceholder.typicode.com/\(url)"
}
private var url: String
required init(url: String) {
self.url = url
}
}Notice how you only need to pass the path and not the domain to each instance that conforms to AlamoRecordURL. That's because you set the domain of each instance in the absolute variable.
This step can be ignored if your server does not return back custom error messages. If this is the case, then base AlamoRecordError objects can be used in return.
Let's assume our API returns custom error messages. Let's create a class that inherits from AlamoRecordError and name it ApplicationError. Let's also assume our JSON structure looks similar to this on failed requests:
{
"status_code": 401,
"message": "You are not authorized to make this request.",
}Our class structure would then look very similar to this:
class ApplicationError: AlamoRecordError {
let statusCode: Int?
let message: String?
private enum CodingKeys: String, CodingKey {
case statusCode = "status_code"
case message
}
}We next need to create an instance of a RequestManager and pass in the ApplicationURL and ApplicationError we just created to the inheritance structure to satisfy the generic requirements. Let's name it ApplicationRequestManager .
// IDType should be of type String or Int
class ApplicationRequestManager: RequestManager<ApplicationURL, ApplicationError, IDType> {
static var `default`: ApplicationRequestManager = ApplicationRequestManager()
init() {
// See the Configuration documentation for all possible options
super.init(configuration: Configuration())
}
}The final step is to create data objects inheriting from AlamoRecordObject that our application needs from our API. In this example, we only have one object named Post.
// IDType should be of type String or Int
class Post: AlamoRecordObject<ApplicationURL, ApplicationError, IDType> {
let userId: Int
let title: String
let body: String
required init(from decoder: Decoder) throws {
let container = try decoder.container(keyedBy: CodingKeys.self)
title = try container.decode(String.self, forKey: .title)
body = try container.decode(String.self, forKey: .body)
try super.init(from: decoder)
}
override class var root: String {
return "post"
}
override class var requestManager: RequestManager<ApplicationURL, ApplicationError, IDType> {
return ApplicationRequestManager
}
private enum CodingKeys: String, CodingKey {
case userId
case title
case body
}
}With this class definition, we would expect each Post json to look like this:
{
"userId": 1,
"id": 1,
"title": "This is a post's title",
"body": "This is the post's body"
}If our Post object was encapsulated in an object like this:
{
"post": {
"userId": 1,
"id": 1,
"title": "This is a post's title",
"body": "This is the post's body"
}
}we would only simply need to override the keyPath in the class declaration:
override class var keyPath: String? {
return "post"
}Notice how the requestManager class variable is overrided and returns the ApplicationRequestManager just created in step 3. Also notice how the root class variable is overrided. Both of these overrides are required for each instance that directly inherits from AlamoRecordObject.
That's it! With just a few lines of code, your networking layer to your application is ready to be used. In the next section, we see all the built in helpers we get by using AlamoRecord.
GET https://jsonplaceholder.typicode.com/posts
Post.all(success: { (posts: [Post]) in
// Do something with the posts
}) { (error) in
// Handle the error
}POST https://jsonplaceholder.typicode.com/posts
let parameters: [String: Any] = ["userId": user.id,
"title": title,
"body": body]
Post.create(parameters: parameters, success: { (post: Post) in
// Do something with the post
}) { (error) in
// Handle the error
}GET https://jsonplaceholder.typicode.com/posts/1
Post.find(id: 1, success: { (post: Post) in
// Do something with the post
}) { (error) in
// Handle the error
}PUT https://jsonplaceholder.typicode.com/posts/1
let parameters: [String: Any] = ["userId": user.id,
"title": title,
"body": body]
post.update(parameters: parameters, success: { (post: Post) in
// Do something with the post
}) { (error) in
// Handle the error
}This can also be done at the class level:
Post.update(id: 1, parameters: parameters, success: { (post: Post) in
// Do something with the post
}) { (error) in
// Handle the error
}DELETE https://jsonplaceholder.typicode.com/posts/1
post.destroy(id: 1, success: {
// The post is now destroyed
}) { (error) in
// Handle the error
}This can also be done at the class level:
Post.destroy(id: 1, success: {
// The post is now destroyed
}) { (error) in
// Handle the error
}requestManager.upload(url: url,
multipartFormData: data,
multipartFormDataName: dataName,
success: { (any: Any?) in
// Upload was successful
}) { (error) in
// Handle the error
}requestManager.download(url: url,
destination: destination,
progress: { (progress) in
// Check the progress
}, success: { (url) in
// Do something with the url
}) { (error) in
// Handle the error
}Providing a destination is optional. If a destination is not provided, then the file will be saved to a temporary location. This file will be overwritten if another download request is made without providing a destination.
Download the example project to see just how easy creating an application that interacts with an API is when using AlamoRecord!
Original concept designed by Rick Pernikoff. AlamoRecord implementation by Dalton Hinterscher.
AlamoRecord is available under the MIT license. See the LICENSE file for more info.