Swiftpack.co - Package - rauhul/api-manager

APIManager

Swift Version Build Status Documentation Converage Release Version GitHub License

APIManager is a framework for abstracting RESTful API requests.

Requirements

  • iOS 11.0+
  • Xcode 9.0+
  • Swift 4.0+

Installation

CocoaPods

CocoaPods is a dependency manager for Cocoa projects. You can install it with the following command:

$ gem install cocoapods

CocoaPods 1.0.0+ is required to build APIManager.

To integrate APIManager into your Xcode project using CocoaPods, specify it in your Podfile:

source 'https://github.com/CocoaPods/Specs.git'
platform :ios, '11.0'
use_frameworks!

target '<Your Target Name>' do
    pod 'APIManager', '~> 0.2.0'
end

Then, run the following command:

$ pod install

Note

APIManager 0.0.5 is the last release with Swift 3 support

Swift Package Manager

The Swift Package Manager is a tool for automating the distribution of Swift code and is integrated into the swift compiler.

Once you have your Swift package set up, adding APIManager as a dependency is as easy as adding it to the dependencies value of your Package.swift.

dependencies: [
    .Package(url: "https://github.com/rauhul/api-manager.git", from: "0.2.0")
]

Usage

APIManager relies on users to create APIServices and APIReturnable types relevent to the RESTful APIs they are working with. APIServices contain descriptions of various endpoints that return their responses as native swift objects.

Making an APIReturnable Type

An APIReturnable Type only needs to conform to one method init(from: Data) throws. APIManager extends Decodable types to also be APIReturnable. An example implementation can be found below:

extension APIReturnable where Self: Decodable {
    init(from data: Data) throws {
        self = try JSONDecoder().decode(Self.self, from: data)
    }
}

Making an APIService

An APIService is made up of 3 components.

  1. A baseURL. Endpoints in this service will be postpended to this URL segment. As a result a baseURL will generally look like the root URL of the API the service communicates with.
open class var baseURL: String {
    return "https://api.example.com"
}
  1. HTTPHeaders to be sent alongside the APIRequests made by the endpoints in your APIService.
open class var headers: HTTPHeaders? {
    return [
        "Content-Type": "application/json"
    ]
}

  1. A set of RESTful api endpoints that you would like to use. These should be simple wrappers around the APIRequest constructor that can take in data (as HTTPParameters and/or HTTPBody as a json dictionary [String: Any]). For example if you would like to get user information by id, the endpoint may look like this:
open class func getUser(byId id: Int) -> APIRequest<ExampleReturnType> {
    return APIRequest<ExampleReturnType>(service: Self, endpoint: "/users", params: ["id": id], body: nil, method: .GET)
}

Using an APIService

Now that you have an APIService, you can use it make RESTful API Requests.

All the RESTful API endpoints we need to access should already be defined in our APIService, so using them is simply a matter of calling them.

Using the example service above, we can make a request to get the User associated with the id 452398:

let request = ExampleService.getUser(byId: 452398)

And subsecquently perform the APIRequest with:

request.perform(withAuthorization: nil)

However, this leaves us unable to access the response nor potential error and additionally requires multiple lines to do what is really one action. Conveniently APIManager allows us to solve this problems with simple chaining syntax. We can specify success, cancellation, and failure blocks. This new request is seen below:

ExampleService.getUser(byId: 452398)
.onSuccess { (returnValue: ReturnType) in
    // Handle Success (Background thread)
    DispatchQueue.main.async {
        // Handle Success (main thread)
    }
}
.onFailure { (error) in
    // Handle Failure (Background thread)
    DispatchQueue.main.async {
        // Handle Failure (main thread)
    }
}
.perform(withAuthorization: nil)

Support

Please open an issue for support.

Contributing

Please contribute using Github Flow. Create a branch, add commits, and open a pull request.

License

This project is licensed under the MIT License. For a full copy of this license take a look at the LICENSE file.

Github

link
Stars: 9
Help us keep the lights on

Dependencies

Used By

Total: 0

Releases

0.2.0 - Jan 10, 2018

Added

  • Failure callback uses swift error type instead of string
  • APIService to filter requests by HTTPResponseCode
  • APIRequestTokens and abillity to cancel requests
  • Cancellation callback

Fixed

  • APIRequest retain cycle
  • Refactor APIService into APIRequest property
  • Potential race conditions

0.1.1 - Nov 19, 2017

Added

  • Added tests both through the xcproj and the swift cli

Fixed

  • Access level bug causing implicit APIReturnable conformance for Codable objects to not be available outside of the APIManager module

Removed

  • tvOS support

0.1.0 - Nov 3, 2017