javier
2b01ec14bf
This PR contains the work done to update the live tests to the latest data plus lots of QoL improvements to the library, including: * added test cases to test the ``AmiiboService` locally; * conformed the models to the `Hashable` protocol; * documented the use of caching with the `AmiiboService` service; * updated the reference to the new AmiiboAPI url; * updated the year on the copyrights and header files; * updated the overall documentation of the source code and the package. Reviewed-on: #22 Co-authored-by: Javier Cicchelli <javier@rock-n-code.com> Co-committed-by: Javier Cicchelli <javier@rock-n-code.com>
140 lines
4.3 KiB
Markdown
140 lines
4.3 KiB
Markdown
# ``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](https://www.amiiboapi.org) 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:
|
|
|
|
```swift
|
|
let package = Package(
|
|
// name, platforms, products, etc.
|
|
dependencies: [
|
|
.package(url: "https://github.com/rock-n-code/amiibo-service", from: "1.4.0"),
|
|
// 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](https://www.amiiboapi.org) 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``:
|
|
|
|
```swift
|
|
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:
|
|
|
|
```swift
|
|
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:
|
|
|
|
```bash
|
|
$ make
|
|
```
|
|
|
|
## Topics
|
|
|
|
### Service
|
|
|
|
- ``AmiiboService``
|
|
|
|
### Clients
|
|
|
|
- ``AmiiboClient``
|
|
- ``AmiiboLiveClient``
|
|
|
|
### Models
|
|
|
|
- ``Amiibo``
|
|
- ``AmiiboSeries``
|
|
- ``AmiiboType``
|
|
- ``GameCharacter``
|
|
- ``GameSeries``
|
|
|
|
### Filters
|
|
|
|
- ``AmiiboFilter``
|
|
- ``AmiiboSeriesFilter``
|
|
- ``AmiiboTypeFilter``
|
|
- ``GameCharacterFilter``
|
|
- ``GameSeriesFilter``
|
|
|
|
### Errors
|
|
|
|
- ``AmiiboServiceError``
|