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: 1738

Dependencies

Releases

5.1.0 - 2019-12-28 07:24:45

  • 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 - 2019-04-17 11:55:50

  • Update to Xcode 10.2 and Swift 5 #268

Thanks @chn-lyzhi for contributing!

4.1.0 - 2019-04-06 00:53:14

  • Support Xcode 10 and Swift 4.2 #265

4.0.0 - 2018-07-25 18:11:50

  • 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 - 2017-12-24 14:41:48

  • Xcode 9 / Swift 4 #252

Thanks @ikesyo for contributing!

4.0.0 beta 1 - 2017-07-23 16:12:24

  • 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 - 2016-12-20 00:56:03

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

Thanks @yshrkt for contributing!

3.1.1 - 2016-12-07 14:14:51

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

Thanks @weiminghuaa for contributing!

3.1.0 - 2016-11-28 17:28:10

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

Thanks @kitasuke for contributing!

3.0.0 - 2016-11-28 17:26:51

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

3.0.0-beta.2 - 2016-09-23 14:31:41

  • Refine APIs to follow the API design guidelines.

3.0.0-beta.1 - 2016-09-17 04:25:34

  • Update API design for Swift 3

2.0.5: Xcode 8 - 2016-07-12 07:24:38

  • 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 - 2016-06-27 19:26:05

  • Enable whole module optimization #184

2.0.3: Fix installing via Carthage - 2016-06-25 15:49:58

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

2.0.2: Swift 2.3 - 2016-06-25 13:12:19

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

2.0.1: Fix subclassing NSURLSessionAdapter - 2016-05-24 16:46:13

2.0.0 - 2016-05-23 00:21:39

: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 - 2016-05-19 16:57:27

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

1.4.1: Use the return value of configureURLRequest(_:) - 2016-05-19 16:30:18

Ref: #140

- 2016-05-18 01:02:44

2.0.0-beta.5 - 2016-05-16 17:04:16

  • [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 - 2016-05-06 12:25:34

  • 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 - 2016-05-04 13:24:42

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

2.0.0-beta.3 - 2016-03-27 18:13:48

  • Migrate to Swift 2.2 syntax.

1.3.0: Swift 2.2 - 2016-03-27 17:06:27

  • Migrate to Swift 2.2 syntax.

2.0.0-beta.2 - 2016-03-21 21:46:05

  • Fixed CocoaPods spec.

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

2.0.0-beta.1 - 2016-03-21 19:50:41

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 - 2016-03-06 13:42:08

  • 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 - 2016-03-05 13:38:50

  • 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!