amiibo-service/Sources/AmiiboService/Catalogs/AmiiboService.docc/Library.md

AmiiboService

A library that provides everything the developer needs to interact with the Amiibo API backend service.

Overview

The amiibo-service library is a package that allows the developer to interact with the Amiibo API backend service seamlessly, by not only providing the service type but also any possible models, filters, errors and interfaces types that might be needed during implementation.

Design

Although it could have been possible to generate a one-to-one RESTful client based on the Open API specification document that describe the available endpoints of the backend service, it was decided to design a AmiiboService service type that removes the complexities of the API design imposed by the backend service, and provides the developer with a simple interface, and a seamless experience.

Installation

To use the AmiiboService library with your package, then add it as a dependency in the Package.swift file:

let package = Package(
    // name, platforms, products, etc.
    dependencies: [
        .package(url: "https://github.com/rock-n-code/amiibo-service", from: "1.4.1"),
        // other dependencies
    ],
    targets: [
        .target(
            name: "SomeTarget", 
            dependencies: [
                .product(name: "AmiiboService", package: "amiibo-service"),
            ]
        )
        // other targets
    ]
)

It is also possible to use the AmiiboService library with your app in Xcode, then add it as a dependency in your Xcode project.

important: Swift 5.10 or higher is required in order to compile this library.

Caching

The Amiibo API recommends that consumers who call the API regularly implement caching on their systems. This library does not include a built-in cache, leaving the choice of caching strategy to the consumer. The following examples show two common approaches.

URLCache on the transport layer

Pass a custom URLSessionTransport with a cache-configured URLSession to AmiiboLiveClient:

import OpenAPIURLSession

let configuration = URLSessionConfiguration.default

configuration.urlCache = URLCache(
    memoryCapacity: 5_000_000,
    diskCapacity: 50_000_000
)

let transport = URLSessionTransport(
    configuration: .init(
        session: URLSession(configuration: configuration)
    )
)

let service = AmiiboService(
    client: AmiiboLiveClient(transport: transport)
)

This leverages HTTP cache headers from the server and persists cached responses to disk.

Application-level caching

Alternatively, cache the results returned by AmiiboService directly in your application using any storage mechanism that fits your needs, such as an in-memory dictionary, a database, or a file-based store.

Testing

The AmiiboClient protocol enables creating custom mock clients for testing, eliminating the need for network calls in unit tests. Conform to AmiiboClient and return stubbed data or throw AmiiboServiceError errors to verify your application's behavior:

import AmiiboService

struct MyMockClient: AmiiboClient {
    var error: AmiiboServiceError?

    func getAmiibos(
        by filter: AmiiboFilter
    ) async throws(AmiiboServiceError) -> [Amiibo] {
        if let error { throw error }
        return []
    }

    // Implement remaining protocol requirements...
}

let service = AmiiboService(client: MyMockClient())

Inject the mock client into AmiiboService via its AmiiboService/init(client:) initializer to test how your code handles empty results, specific errors, or any other scenario without relying on the live backend.

Tasks

This library offers a set of ready-to-use tasks that simplify the interaction with the library, which the developer can use from any Terminal application.

Tip: To show the available list of tasks, plus display some explanations about each and every one of them; please enter the following command:

$ make

Topics

Service

• AmiiboService

Clients

• AmiiboClient
• AmiiboLiveClient

Models

• Amiibo
• AmiiboSeries
• AmiiboType
• GameCharacter
• GameSeries

Filters

• AmiiboFilter
• AmiiboSeriesFilter
• AmiiboTypeFilter
• GameCharacterFilter
• GameSeriesFilter

Errors

• AmiiboServiceError