search

steamclock / netable

A Swift library for encapsulating network APIs using Codable in a type-oriented way.
MIT License
99 stars 3 forks source link
swift

readme

Swift Package Manager compatiblePRs WelcomeLicense: MIT Platform

Modern apps interact with a lot of different APIs. Netable makes that easier by providing a simple interface for using those APIs to drive high-quality iOS and MacOS apps, built on Swift Codable, while still supporting non-standard and unusual APIs when need be.

Features

Netable is built on a number of core principles we believe a networking library should follow:

Usage

Standard Usage

Make a new instance of Netable, and pass in your base URL:

let netable = Netable(baseURL: URL(string: "https://api.thecatapi.com/v1/")!)

See here for information on adding additional instance parameters.

Extend Request

struct CatImage: Decodable {
    let id: String
    let url: String
}

struct GetCatImages: Request {
    typealias Parameters = [String: String]
    typealias RawResource = [CatImage]

    public var method: HTTPMethod { return .get }

    public var path: String {
        return "images/search"
    }

    public var parameters: [String: String] {
        return ["mime_type": "jpg,png", "limit": "2"]
    }
}

Make your request using async/await and handle the result:

Task {
    do {
        let catImages = try await netable.request(GetCatImages())
        if let firstCat = catImages.first,
           let url = URL(string: firstCat.url),
           let imageData = try? Data(contentsOf: url) {
            self.catsImageView1.image = UIImage(data: imageData)
        }

        if let lastCat = catImages.last,
           let url = URL(string: lastCat.url),
           let imageData = try? Data(contentsOf: url) {
            self.catsImageView2.image = UIImage(data: imageData)
        }
    } catch {
        let alert = UIAlertController(
            title: "Uh oh!",
            message: "Get cats request failed with error: \(error)",
            preferredStyle: .alert
        )

        alert.addAction(UIAlertAction(title: "OK", style: .cancel))
        self.present(alert, animated: true, completion: nil)
    }
}

Making a request with Combine

netable.request(GetCatImages())
    .sink { result in
        switch result {
        case .success(let catImages):
            if let firstCat = catImages.first,
               let url = URL(string: firstCat.url),
               let imageData = try? Data(contentsOf: url) {
                self.catsImageView1.image = UIImage(data: imageData)
            }

            if let lastCat = catImages.last,
               let url = URL(string: lastCat.url),
               let imageData = try? Data(contentsOf: url) {
                self.catsImageView2.image = UIImage(data: imageData)
            }
        case .failure(let error):
            let alert = UIAlertController(
                title: "Uh oh!",
                message: "Get cats request failed with error: \(error)",
                preferredStyle: .alert
            )

            alert.addAction(UIAlertAction(title: "OK", style: .cancel))
            self.present(alert, animated: true, completion: nil)
        }
    }.store(in: &cancellables)

Or, if you prefer good old fashioned callbacks

netable.request(GetCatImages()) { result in
    switch result {
    case .success(let catImages):
        if let firstCat = catImages.first,
           let url = URL(string: firstCat.url),
           let imageData = try? Data(contentsOf: url) {
            self.catsImageView1.image = UIImage(data: imageData)
        }

        if let lastCat = catImages.last,
           let url = URL(string: lastCat.url),
           let imageData = try? Data(contentsOf: url) {
            self.catsImageView2.image = UIImage(data: imageData)
        }
    case .failure(let error):
        let alert = UIAlertController(
            title: "Uh oh!",
            message: "Get cats request failed with error: \(error)",
            preferredStyle: .alert
        )

        alert.addAction(UIAlertAction(title: "OK", style: .cancel))
        self.present(alert, animated: true, completion: nil)
    }
}

Canceling A Request

You're able to easily cancel a request using .cancel(), which you can see in action in the AuthNetworkService within the Example Project.

To cancel a task, we first need to ensure we retain a reference to the task, like so: 

 let createRequest = Task {
               let result = try await netable.request()
}

createRequest.cancel()

Additional Netable instance parameters

Within your Netable Instance, you're able to provide optional parameters beyond the baseURL to send additional information with each request made. These include:

  let netable = Netable(baseURL: URL(string: "https://...")!,
            config: Config(globalHeaders: ["Authentication" : "Bearer \(login.token)"]),
            logDestination: EmptyLogDestination(),
            retryConfiguration: RetryConfiguration(errors: .all, count: 3, delay: 5.0),
            requestFailureDelegate: ErrorService.shared)

See AuthNetworkService in the Example Project for a more detailed example.

Additional Request parameters

You also have the flexibility to set optional parameters to be sent along with each individual request made to an instance. Note that for duplicated parameters between an instance and an individual request, the instance's paramters will be overridden by an individual request. You can see the list of these here.

Within the Example Project, you can see an example of adding unredactedParameterKeys within the LoginRequest and a jsonKeyDecodingStrategy within the GetUserRequest.

Resource Extraction

Have your request object handle extracting a usable object from the raw resource

struct CatImage: Decodable {
    let id: String
    let url: String
}

struct GetCatImageURL: Request {
    typealias Parameters = [String: String]
    typealias RawResource = [CatImage]
    typealias FinalResource = URL

     // ...

    func finalize(raw: RawResource) async throws -> FinalResource {
        guard let catImage = raw.first else {
            throw NetableError.resourceExtractionError("The CatImage array is empty")
        }

        guard let url = URL(string: catImage.url) else {
            throw NetableError.resourceExtractionError("Could not build URL from CatImage url string")
        }

        return url
    }
}

Leave your network code to deal with the important stuff

Task { 
    do {
        let catUrl = try await netable.request(GetCatImages())
        guard let imageData = try? Data(contentsOf: catUrl) else {
            throw NetableError.noData
        }

        self.imageView.image = UIImage(data: imageData)
    } catch {
        // ...
    }
}

Smart Unwrapping Objects

Sometimes APIs like to return the object you actually care about inside of a single level wrapper, which Finalize is great at dealing with, but requires a little more boilerplate code than we'd like. This is where SmartUnwrap<> comes in!

Create your request as normal, but set your RawResource = SmartUnwrap<ObjectYouCareAbout> and FinalResource = ObjectYourCareAbout. You can also specify Request.smartUnwrapKey to avoid ambiguity when unwrapping objects from your response.

Before: 

struct UserResponse {
    let user: User
}

struct User {
    let name: String
    let email: String
}

struct GetUserRequest: Request {
    typealias Parameters: GetUserParams
    typealias RawResource: UserResponse
    typealias FinalResource: User

    // ...

    func finalize(raw: RawResource) async throws -> FinalResource {
        return raw.user
    }
}

After: 

struct User: {
    let name: String
    let email: String
}

struct GetUserRequest: Request {
    typealias Parameters: GetUserParams
    typealias RawResource: SmartUnwrap<User>
    typealias FinalResource: User
}

Partially Decoding Arrays

Sometimes, when decoding an array of objects, you may not want to fail the entire request if some of those objects fail to decode. For example, the following json would fail to decode using standard decoding because the second post is missing the content.

{ 
    posts: [
        { 
        "title": "Super cool cat."
        "content": "Info about a super cool cat."
        },
        {
        "title": "Even cooler cat."
        }
    ]
}

To do this, you can set your Request's arrayDecodeStrategy to .lossy to return any elements that succeed to decode.

struct Post: {
   let title: String
   let content: String
}

struct GetPostsRequests: {
typealias RawResource: SmartUnwrap<[Post]>
typealias FinalResource: [Post]

var arrayDecodingStrategy: ArrayDecodingStrategy: { return .lossy }
}

Note that this will only work if your RawResource is RawResource: Sequence or RawResource: SmartUnwrap<Sequence>. For better support of decoding nested, lossy arrays we recommend checking out Better Codable. Also, at this time, Netable doesn't support partial decoding for GraphQL requests.

Create a LossyArray directly within your object

Using .lossy as our arrayDecodingStrategy works well for objects that are being decoded as an array. We've added support to allow for partial decoding of objects that contain arrays.

struct User: Decodable {
    let firstName: String
    let lastName: String
    let bio: String
    let additionalInfo: LossyArray<AdditionalInfo>
}

struct UserLoginData: Decodable, Hashable {
    let age: Int
    let gender: String
    let nickname: String
}

Note: to access the LossyArray's elements, you have to access .element within, like so.

    ForEach(user.additionalInfo.element, id: \.self) {
    // ..
    }

Perform an optional process before returning the result using postProcess

This is helpful for managing data in places like caches or data managers. You can see this more indepth in our UserRequest

To use postProcess inside of the request, add the code you want to run before the return statement:


struct GetUserRequest: Request {
   // ...

    func postProcess(result: FinalResource) -> FinalResource {
        DataManager.shared.user = result
        return result
    }
}

Handling Errors

In addition to handling errors locally that are thrown, or returned through Result objects, we provide two ways to handle errors globally. These can be useful for doing things like presenting errors in the UI for common error cases across multiple requests, or catching things like failed authentication requests to clear a stored user.

Using requestFailureDelegate

See GlobalRequestFailureDelegate in the Example project for a more detailed example.

extension GlobalRequestFailureDelegateExample: RequestFailureDelegate {
    func requestDidFail<T>(_ request: T, error: NetableError) where T : Request {
        let alert = UIAlertController(title: "Uh oh!", message: error.errorDescription, preferredStyle: .alert)
        present(alert, animated: true)
    }
}

Request Interceptors

Interceptors are a powerful and flexible way to modify a Request before it is executed. When you create your Netable instance, you can pass in an optional InterceptorList, containing any Interceptors you would like to be applied to requests.

When you make a request, each Interceptor will call its adapt function in turn, in the order it was passed in to the InterceptorList. adapt should return a special AdaptedRequest object that indicates the result of the function call.

You might attached a new header, modifying the request:

func adapt(_ request: URLRequest, instance: Netable) async throws -> AdaptedRequest {
    var newRequest = request
    newRequest.addValue("1a2a3a4a", forHTTPHeaderField: "Authorization")
    return .changed(newRequest)
}

Or, you might sub out the entire request with a mocked file for specific endpoints, otherwise do nothing:

func adapt(_ request: URLRequest, instance: Netable) async throws -> AdaptedRequest {
    if request.url.contains("/foo") {
        return .mocked("./path/to/foo-mock.json")
    } else if request.url.contains("/bar") {
        return .mocked("./path/to/bar-mock.json")
    }

    return .notChanged
}

See MockRequestInterceptor in the Example project for a more detailed example.

Using requestFailurePublisher

If you prefer Combine, you can subscribe to this publisher to receive NetableErrors from elsewhere in your app.

See GlobalRequestFailurePublisher in the Example project for a more detailed example.

netable.requestFailurePublisher.sink { error in
    let alert = UIAlertController(title: "Uh oh!", message: error.errorDescription, preferredStyle: .alert)
    self.present(alert, animated: true)
}.store(in: &cancellables)

Using FallbackResource

Sometimes, you may want to specify a backup type to try and decode your response to if the initial decoding fails, for example:

Request allows you to optionally declare a FallbackResource: Decodable associated type when creating your request. If you do and your request fails to decode the RawResource, it will try to decode your fallback resource, and if successful, throw a NetableError.fallbackDecode with your successful decoding.

struct CoolCat {
    let name: String
    let breed: String
}

struct Cat {
    let name: String
}

struct GetCatRequest: Request {
typealias RawResource: CoolCat
typealias FallbackResource: Cat

// ...
}

See FallbackDecoderViewController in the Example project for a more detailed example.

GraphQL Support

While you can technically use Netable to manage GraphQL queries right out of the box, we've added a helper protocol to make your life a little bit easier, called GraphQLRequest.

struct GetAllPostsQuery: GraphQLRequest {
    typealias Parameters = Empty
    typealias RawResource = SmartUnwrap<[Post]>
    typealias FinalResource = [Post]

    var source = GraphQLQuerySource.resource("GetAllPostsQuery")
}

See UpdatePostsMutation in the Example Project for a more detailed example. Note that by default it's important that your .graphql file's name matches exactly with your request.

We recommend using a tool like Postman to document and test your queries. Also note that currently, shared fragments are not supported.

Example

Full Documentation

In-depth documentation is provided through Jazzy and GitHub Pages.

Installation

Requirements

Netable is available through Swift Package Manager. To install it, follow these steps:

  1. In Xcode, click File, then Swift Package Manager, then Add Package Dependency
  2. Choose your project
  3. Enter this URL in the search bar https://github.com/steamclock/netable.git

Supporting earlier version of iOS

Since Netable 2.0 leverages async/await under the hood, if you want to build for iOS versions before 15.0 you'll need to use v1.0.

License

Netable is available under the MIT license. See the License.md for more info.