SwiftRestAPIClient

SwiftRestAPIClient is a framework written in Swift that makes it easy for you to build a Rest API client for you application.

• [Features] (#features)
• [The Basics] (#example-usage)

Features

• Base skeleton system for a client
• Generic types on requests and responses
• Error handling
• Configuration of the client

Example Usage

First you need to configure the API Client by implementing the APIConfiguration protocol which includes the following:

/// Base URL of the API
var baseUrl: String { get }

/// The default HTTP Headers that will be sent for every request
var headers: [String: String] { get }

// The minimum acceptable status code for the backend
var minStatusCode: Int { get }

// The maximum acceptable status code for the backend
var maxStatusCode: Int { get }

For example: class MyConfiguration: APIConfiguration

Then, in AppDelegate.swift, set the configuration of the client:

import SwiftRestAPIClient

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: 
[UIApplicationLaunchOptionsKey: Any]?) -> Bool {
    APIClient.shared.configuration = MyConfiguration()
    return true
}

Now the configuration has been set, its time to set the requests. This is pretty straight forward, you just need to understand how the APIClient, APIRequest and APIResponse work together. The client sends a request to the server and returns a response that is declared in the request. The APIClient is already a class that's working so you don't need to subclass that. Let's think of an example backend application that has users and the users can create posts and comments. We could have endpoints like these: GET /posts POST /posts POST /users/login

Before implementing the requests we need to figure out what kind of responses we want to receive. Usually a request returns one object or an array of objects. There are two classes implementing the APIResponse protocol: ObjectResponse and ArrayResponse. As you can tell one of them is for returning objects and the other is for returning an array of objects. These objects must implement the Codable protocol. Codable is a Swift library presented in Swift 4. I'd recommend you to check this guide if you don't know how to use it.

For a GET request like GET /posts?limit=5&offset=10 you can implement the APIRequest``` protocol in the following way:

class GetPostsRequest {
    typealias Response = ArrayResponse<Post>

    var resourceName: String {
        return "/posts"
    }

    var method: APIMethod {
        return .get
    }

    var parameters: [String: Any] = [:]
    
    init(limit: Int, offset: Int) {
        parameters["limit"] = limit
        parameters["offset"] = offset
    }
}

For a POST request like POST /posts/5/comments to create a comment object you can do the following:

class PostPostRequest {
    typealias Response = ObjectResponse<Comment>

    var resourceName: String {
        return "/post/\(postId)/comments"
    }

    var method: APIMethod {
        return .post
    }

    var parameters: [String: Any] = [:]
    
    var postId: Int
    
    init(post: Post) {
        self.postId = post.id
        parameters["message"] = post.message
        parameters["createdBy"] = post.user.id
    }
}

APIRequest also has two more features: headers and callback. For example if you're sending a login request as a POST, you might want to add a Basic Auth header and save the resulting data (e.g. a token) that you get from the server. Implementing this is easy:

class UserLoginRequest {
    
    private var username: String
    private var password: String
    
    init(username: String, password: String) {
        self.username = username
        self.password = password
    }
    
    var headers: HTTPHeaders {
        var headers: HTTPHeaders = [:]
        if let authorizationHeader = Request.authorizationHeader(user: username, password: password) {
            headers[authorizationHeader.key] = authorizationHeader.value
        }
        return headers
    }
    
    func callback(item: UserLoginRequest.Response) {
        // item.result is the response object
        // here you can save it like
        // this function is called after the request is completed
        Keychain.save(item.result)
    }
}

Finally, calling these requests is really simple:

let request = APIClient.shared.send(GetPostsRequest(limit: 10, offset: 5), objectBlock: { (response) in
    if (reponse.success) {
        // do something with response.result
        // you will see that response.result is the type that you want
    } else {
        // handle response.error
    }
})

Example

To run the example project, clone the repo, and run pod install from the Example directory first.

Requirements

Installation

SwiftRestAPIClient is available through CocoaPods. To install it, simply add the following line to your Podfile:

pod 'SwiftRestAPIClient'

Author

kha26, [email protected]

License

SwiftRestAPIClient is available under the MIT license. See the LICENSE file for more info.