Swiftpack.co - Package - ishkawa/APIKit

APIKit

Build Status codecov Carthage compatible Version Platform Swift Package Manager

APIKit is a type-safe networking abstraction layer that associates request type with response type.

// SearchRepositoriesRequest conforms to Request protocol.
let request = SearchRepositoriesRequest(query: "swift")

// Session receives an instance of a type that conforms to Request.
Session.send(request) { result in
    switch result {
    case .success(let response):
        // Type of `response` is `[Repository]`,
        // which is inferred from `SearchRepositoriesRequest`.
        print(response)

    case .failure(let error):
        self.printError(error)
    }
}

Requirements

  • Swift 5.0 or later
  • iOS 8.0 or later
  • Mac OS 10.10 or later
  • watchOS 2.0 or later
  • tvOS 9.0 or later

If you use Swift 2.2 or 2.3, try APIKit 2.0.5.

If you use Swift 4.2 or before, try APIKit 4.1.0.

Installation

Carthage

  • Insert github "ishkawa/APIKit" ~> 5.0 to your Cartfile.
  • Run carthage update.
  • Link your app with APIKit.framework in Carthage/Build.

CocoaPods

  • Insert pod 'APIKit', '~> 5.0' to your Podfile.
  • Run pod install.

Note: CocoaPods 1.4.0 is required to install APIKit 5.

Documentation

Advanced Guides

Migration Guides

Github

link
Stars: 1757

Dependencies

Releases

5.1.0 -

  • Remove to link Result.framework from README.md #274
  • Fix typo #276
  • [Swift 5.1] Enable Module Stability #278

Thanks @jumperson and @onevcat for contributing!

5.0.0 -

  • Update to Xcode 10.2 and Swift 5 #268

Thanks @chn-lyzhi for contributing!

4.1.0 -

  • Support Xcode 10 and Swift 4.2 #265

4.0.0 -

  • Update Result dependency to 4.0.
  • Minor update for Xcode 9.3 and Swift 4.1 support.

Thanks @ikesyo and @KyoheiG3 for contributing!

3.2.0 -

  • Xcode 9 / Swift 4 #252

Thanks @ikesyo for contributing!

4.0.0 beta 1 -

  • Add progressHandler parameter to sendRequest(_:) method.
  • Introduce Request.DataParser associated type to express various data format such as JSON, URL query and Protobuf.
  • Introduce QueryParameters protocol for custom URL query parsers.

3.1.2 -

  • Expose CallbackQueue.execute() for customization. #221

Thanks @yshrkt for contributing!

3.1.1 -

  • Remove redundant resume() call in URLSessionAdapter. #218

Thanks @weiminghuaa for contributing!

3.1.0 -

  • Add ProtobufDataParser for protocol buffers. #214
  • Update build settings for Xcode 8.1. #213

Thanks @kitasuke for contributing!

3.0.0 -

  • Swift 3 support.
  • Follow Swift 3 API guidelines.

3.0.0-beta.2 -

  • Refine APIs to follow the API design guidelines.

3.0.0-beta.1 -

  • Update API design for Swift 3

2.0.5: Xcode 8 -

  • Update code signing config to fix build for devices on Xcode 8. #185
  • Result and OHHTTPStubs are also updated.

Thanks @ikesyo!

2.0.4: Whole module optimization -

  • Enable whole module optimization #184

2.0.3: Fix installing via Carthage -

  • Disable whole module optimization to avoid build error while carthage build #183

2.0.2: Swift 2.3 -

  • Support Swift 2.3 #179
  • Make HTTPMethod.prefersQueryParameters public #180

2.0.1: Fix subclassing NSURLSessionAdapter -

2.0.0 -

:tada:

APIKit 2 introduces 3 major features below:

  • New error handling model
  • Convenience parameters and actual parameters
  • Abstraction of networking backend

See the migration guide and following summary for more details.

New error handling model

The error type of Session.sendRequest(_:) is changed to SessionTaskError:

public enum SessionTaskError: ErrorType {
    case ConnectionError(ErrorType)
    case RequestError(ErrorType)
    case ResponseError(ErrorType)
}

These error cases describes where the error occurred, not what is the error. You can throw any kind of error to notify what is happened in the following methods:

public protocol RequestType {
    ...

    // The error thrown here will be the associated value of SessionTaskError.RequestError 
    func interceptURLRequest(URLRequest: NSMutableURLRequest) throws -> NSMutableURLRequest

    // The error thrown here will be the associated value of SessionTaskError.ResponseError 
    func interceptObject(object: AnyObject, URLResponse: NSHTTPURLResponse) throws -> AnyObject
}

Convenience parameters and actual parameters

Usually, you can specify request parameters in dictionary-literal or array-literal like below:

struct SomeRequest: RequestType {
    ...

    var parameters: AnyObject? {
        return ["q": "Swift"]
    }
}

var parameters is the convenience parameters. It is define as below:

public protocol RequestType {
    ...

    var parameters: AnyObject? { get }
}

Actually, we have to translate the literal into HTTP/HTTPS request. There are 2 places to express parameters, URL query and body. RequestType has interface to express them, var queryParameters: [String: AnyObject]? and var bodyParameters: BodyParametersType?. Those are the actual parameters.

public protocol RequestType {
    ...

    var queryParameters: [String: AnyObject]? { get }
    var bodyParameters: BodyParametersType? { get }
}

If you implement convenience parameters only, the actual parameters are computed from the convenience parameters depending on HTTP method.

APIKit provides 3 types that conforms to BodyParametersType:

Name Parameters Type
JSONBodyParameters AnyObject
FormURLEncodedBodyParameters [String: AnyObject]
MultipartFormDataBodyParameters [MultipartFormDataBodyParameters.Part]

Abstraction of networking backend

APIKit uses NSURLSession as networking backend by default. Since Session in APIKit 2 has abstraction layer of backend called SessionAdapterType, you can change the backend of Session like below:

Demo implementation of Alamofire adapter is available here.

2.0.0-beta.7 -

  • [Fixed] Use the return value of interceptURLRequest(_:).

1.4.1: Use the return value of configureURLRequest(_:) -

Ref: #140

-

2.0.0-beta.5 -

  • [Renamed] HTTPHeaderFields in RequestType is renamed to headerFields.
  • [Renamed] resumedTaskWithURLRequest(_:) is renamed to createTaskWithURLRequest(_:).
  • [Added] resume() is added to SessionTaskType.
  • [Added] StringDataParser is added for unformatted response body.
  • [Changed] Exposed RequestError.
  • [Changed] Type of associated value of SessionTaskError.ConnectionError is changed from NSError to ErrorType.

2.0.0-beta.4 -

  • MultipartFormDataParameters uses NSInputStream for its entity. #160
  • Session.sharedSession is changed to class property for overriding. #158
  • Add callbackQueue parameter to Session.sendRequest(). #157 #156

Thanks to @jyounus and @kumabook for the contribution!

1.4.0: Extensible shared session -

  • Session.sharedSession is now class property so that you can override it. #158

2.0.0-beta.3 -

  • Migrate to Swift 2.2 syntax.

1.3.0: Swift 2.2 -

  • Migrate to Swift 2.2 syntax.

2.0.0-beta.2 -

  • Fixed CocoaPods spec.

NOTE: Since APIKit 2 is beta software, breaking changes will continue to occur.

2.0.0-beta.1 -

Major changes are listed below:

This release also contains minor renames of several APIs. Check out the migration guide for more details.

NOTE: Since APIKit 2 is beta software, breaking changes will continue to occur.

1.2.1: App Extensions -

  • Set APPLICATION_EXTENSION_API_ONLY YES to fix linker issue in app extensions. #133

Thank you @toshi0383 !!!

1.2.0: multipart/form-data, SPM and JSON-RPC -

  • Add .MultipartFormData to RequestBodyBuilder. #128
  • Support building via Swift Package Manager. #130
  • Add a secondary property objectParameters for the array parameters, which is for batch requests in JSON-RPC. #125

Thank you to @ninjinkun and @toshi0383 for the patches!