amiibo-service/docs/data/documentation/amiiboservice.json

{"schemaVersion":{"patch":0,"minor":3,"major":0},"abstract":[{"type":"text","text":"A library that provides everything the developer needs to interact with the "},{"inlineContent":[{"text":"Amiibo API","type":"text"}],"type":"strong"},{"text":" backend service.","type":"text"}],"hierarchy":{"paths":[[]]},"variants":[{"traits":[{"interfaceLanguage":"swift"}],"paths":["\/documentation\/amiiboservice"]}],"sections":[],"kind":"symbol","metadata":{"modules":[{"name":"AmiiboService"}],"role":"collection","externalID":"AmiiboService","title":"AmiiboService","symbolKind":"module","roleHeading":"Framework"},"topicSections":[{"identifiers":["doc:\/\/AmiiboService\/documentation\/AmiiboService\/AmiiboService"],"title":"Service","anchor":"Service"},{"identifiers":["doc:\/\/AmiiboService\/documentation\/AmiiboService\/AmiiboClient","doc:\/\/AmiiboService\/documentation\/AmiiboService\/AmiiboLiveClient"],"title":"Clients","anchor":"Clients"},{"identifiers":["doc:\/\/AmiiboService\/documentation\/AmiiboService\/Amiibo","doc:\/\/AmiiboService\/documentation\/AmiiboService\/AmiiboSeries","doc:\/\/AmiiboService\/documentation\/AmiiboService\/AmiiboType","doc:\/\/AmiiboService\/documentation\/AmiiboService\/GameCharacter","doc:\/\/AmiiboService\/documentation\/AmiiboService\/GameSeries"],"title":"Models","anchor":"Models"},{"identifiers":["doc:\/\/AmiiboService\/documentation\/AmiiboService\/AmiiboFilter","doc:\/\/AmiiboService\/documentation\/AmiiboService\/AmiiboSeriesFilter","doc:\/\/AmiiboService\/documentation\/AmiiboService\/AmiiboTypeFilter","doc:\/\/AmiiboService\/documentation\/AmiiboService\/GameCharacterFilter","doc:\/\/AmiiboService\/documentation\/AmiiboService\/GameSeriesFilter"],"title":"Filters","anchor":"Filters"},{"identifiers":["doc:\/\/AmiiboService\/documentation\/AmiiboService\/AmiiboServiceError"],"title":"Errors","anchor":"Errors"}],"primaryContentSections":[{"kind":"content","content":[{"text":"Overview","level":2,"anchor":"Overview","type":"heading"},{"inlineContent":[{"text":"The ","type":"text"},{"code":"amiibo-service","type":"codeVoice"},{"text":" library is a package that allows the developer to interact with the ","type":"text"},{"isActive":true,"identifier":"https:\/\/www.amiiboapi.org","type":"reference"},{"text":" backend service seamlessly, by not only providing the ","type":"text"},{"inlineContent":[{"text":"service","type":"text"}],"type":"emphasis"},{"text":" type but also any possible ","type":"text"},{"inlineContent":[{"type":"text","text":"models"}],"type":"emphasis"},{"text":", ","type":"text"},{"inlineContent":[{"text":"filters","type":"text"}],"type":"emphasis"},{"text":", ","type":"text"},{"inlineContent":[{"text":"errors","type":"text"}],"type":"emphasis"},{"text":" and ","type":"text"},{"inlineContent":[{"text":"interfaces","type":"text"}],"type":"emphasis"},{"text":" types that might be needed during implementation.","type":"text"}],"type":"paragraph"},{"anchor":"Design","text":"Design","type":"heading","level":2},{"type":"paragraph","inlineContent":[{"type":"text","text":"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 "},{"code":"AmiiboService","type":"codeVoice"},{"type":"text","text":" 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."}]},{"anchor":"Installation","text":"Installation","type":"heading","level":2},{"type":"paragraph","inlineContent":[{"type":"text","text":"To use the "},{"type":"codeVoice","code":"AmiiboService"},{"type":"text","text":" library with your package, then add it as a dependency in the "},{"type":"codeVoice","code":"Package.swift"},{"type":"text","text":" file:"}]},{"type":"codeListing","syntax":"swift","code":["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","    ]",")"]},{"type":"paragraph","inlineContent":[{"text":"It is also possible to use the ","type":"text"},{"code":"AmiiboService","type":"codeVoice"},{"text":" library with your app in Xcode, then add it as a dependency in your Xcode project.","type":"text"}]},{"style":"important","content":[{"type":"paragraph","inlineContent":[{"text":"Swift 5.10 or higher is required in order to compile this library.","type":"text"}]}],"name":"Important","type":"aside"},{"anchor":"Caching","type":"heading","level":2,"text":"Caching"},{"type":"paragraph","inlineContent":[{"text":"The ","type":"text"},{"identifier":"https:\/\/www.amiiboapi.org","overridingTitle":"Amiibo API","overridingTitleInlineContent":[{"type":"text","text":"Amiibo API"}],"isActive":true,"type":"reference"},{"type":"text","text":" 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."}]},{"level":3,"anchor":"URLCache-on-the-transport-layer","type":"heading","text":"URLCache on the transport layer"},{"inlineContent":[{"type":"text","text":"Pass a custom "},{"code":"URLSessionTransport","type":"codeVoice"},{"type":"text","text":" with a cache-configured "},{"code":"URLSession","type":"codeVoice"},{"type":"text","text":" to "},{"isActive":true,"identifier":"doc:\/\/AmiiboService\/documentation\/AmiiboService\/AmiiboLiveClient","type":"reference"},{"type":"text","text":":"}],"type":"paragraph"},{"syntax":"swift","type":"codeListing","code":["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)",")"]},{"type":"paragraph","inlineContent":[{"type":"text","text":"This leverages HTTP cache headers from the server and persists cached responses to disk."}]},{"level":3,"type":"heading","text":"Application-level caching","anchor":"Application-level-caching"},{"inlineContent":[{"type":"text","text":"Alternatively, cache the results returned by "},{"type":"reference","identifier":"doc:\/\/AmiiboService\/documentation\/AmiiboService\/AmiiboService","isActive":true},{"type":"text","text":" 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."}],"type":"paragraph"},{"level":2,"type":"heading","text":"Testing","anchor":"Testing"},{"inlineContent":[{"type":"text","text":"The "},{"isActive":true,"type":"reference","identifier":"doc:\/\/AmiiboService\/documentation\/AmiiboService\/AmiiboClient"},{"type":"text","text":" protocol enables creating custom mock clients for testing, eliminating the need for network calls in unit tests. Conform to "},{"isActive":true,"type":"reference","identifier":"doc:\/\/AmiiboService\/documentation\/AmiiboService\/AmiiboClient"},{"type":"text","text":" and return stubbed data or throw "},{"isActive":true,"type":"reference","identifier":"doc:\/\/AmiiboService\/documentation\/AmiiboService\/AmiiboServiceError"},{"type":"text","text":" errors to verify your application’s behavior:"}],"type":"paragraph"},{"syntax":"swift","type":"codeListing","code":["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())"]},{"type":"paragraph","inlineContent":[{"type":"text","text":"Inject the mock client into "},{"type":"reference","isActive":true,"identifier":"doc:\/\/AmiiboService\/documentation\/AmiiboService\/AmiiboService"},{"text":" via its ","type":"text"},{"type":"reference","isActive":true,"identifier":"doc:\/\/AmiiboService\/documentation\/AmiiboService\/AmiiboService\/init(client:)"},{"text":" initializer to test how your code handles empty results, specific errors, or any other scenario without relying on the live backend.","type":"text"}]},{"level":2,"text":"Tasks","type":"heading","anchor":"Tasks"},{"inlineContent":[{"text":"This library offers a set of ready-to-use tasks that simplify the interaction with the library, which the developer can use from any ","type":"text"},{"code":"Terminal","type":"codeVoice"},{"text":" application.","type":"text"}],"type":"paragraph"},{"style":"tip","name":"Tip","content":[{"inlineContent":[{"text":"To show the available list of tasks, plus display some explanations about each and every one of them; please enter the following command:","type":"text"}],"type":"paragraph"}],"type":"aside"},{"code":["$ make"],"type":"codeListing","syntax":"bash"}]}],"identifier":{"interfaceLanguage":"swift","url":"doc:\/\/AmiiboService\/documentation\/AmiiboService"},"references":{"https://www.amiiboapi.org":{"type":"link","identifier":"https:\/\/www.amiiboapi.org","titleInlineContent":[{"text":"Amiibo API","type":"text"}],"title":"Amiibo API","url":"https:\/\/www.amiiboapi.org"},"doc://AmiiboService/documentation/AmiiboService/Amiibo":{"abstract":[{"text":"A model that represents an amiibo.","type":"text"}],"navigatorTitle":[{"kind":"identifier","text":"Amiibo"}],"role":"symbol","identifier":"doc:\/\/AmiiboService\/documentation\/AmiiboService\/Amiibo","type":"topic","title":"Amiibo","url":"\/documentation\/amiiboservice\/amiibo","fragments":[{"kind":"keyword","text":"struct"},{"text":" ","kind":"text"},{"text":"Amiibo","kind":"identifier"}],"kind":"symbol"},"doc://AmiiboService/documentation/AmiiboService/AmiiboSeries":{"fragments":[{"text":"struct","kind":"keyword"},{"text":" ","kind":"text"},{"text":"AmiiboSeries","kind":"identifier"}],"navigatorTitle":[{"text":"AmiiboSeries","kind":"identifier"}],"kind":"symbol","role":"symbol","identifier":"doc:\/\/AmiiboService\/documentation\/AmiiboService\/AmiiboSeries","abstract":[{"type":"text","text":"A model that represents an amiibo series."}],"url":"\/documentation\/amiiboservice\/amiiboseries","type":"topic","title":"AmiiboSeries"},"doc://AmiiboService/documentation/AmiiboService/AmiiboServiceError":{"abstract":[{"type":"text","text":"A representation of all the possible errors that the "},{"identifier":"doc:\/\/AmiiboService\/documentation\/AmiiboService\/AmiiboService","isActive":true,"type":"reference"},{"text":" service could throw.","type":"text"}],"kind":"symbol","role":"symbol","url":"\/documentation\/amiiboservice\/amiiboserviceerror","fragments":[{"text":"enum","kind":"keyword"},{"text":" ","kind":"text"},{"text":"AmiiboServiceError","kind":"identifier"}],"identifier":"doc:\/\/AmiiboService\/documentation\/AmiiboService\/AmiiboServiceError","title":"AmiiboServiceError","navigatorTitle":[{"kind":"identifier","text":"AmiiboServiceError"}],"type":"topic"},"doc://AmiiboService/documentation/AmiiboService/AmiiboService/init(client:)":{"url":"\/documentation\/amiiboservice\/amiiboservice\/init(client:)","kind":"symbol","fragments":[{"text":"init","kind":"identifier"},{"text":"(","kind":"text"},{"text":"client","kind":"externalParam"},{"text":": ","kind":"text"},{"kind":"keyword","text":"some"},{"text":" ","kind":"text"},{"text":"AmiiboClient","preciseIdentifier":"s:13AmiiboService0A6ClientP","kind":"typeIdentifier"},{"text":")","kind":"text"}],"type":"topic","abstract":[{"text":"Initializes this service with a specific client type.","type":"text"}],"identifier":"doc:\/\/AmiiboService\/documentation\/AmiiboService\/AmiiboService\/init(client:)","title":"init(client:)","role":"symbol"},"doc://AmiiboService/documentation/AmiiboService":{"title":"AmiiboService","kind":"symbol","type":"topic","abstract":[{"text":"A library that provides everything the developer needs to interact with the ","type":"text"},{"inlineContent":[{"text":"Amiibo API","type":"text"}],"type":"strong"},{"type":"text","text":" backend service."}],"identifier":"doc:\/\/AmiiboService\/documentation\/AmiiboService","url":"\/documentation\/amiiboservice","role":"collection"},"doc://AmiiboService/documentation/AmiiboService/AmiiboFilter":{"kind":"symbol","url":"\/documentation\/amiiboservice\/amiibofilter","fragments":[{"kind":"keyword","text":"struct"},{"text":" ","kind":"text"},{"kind":"identifier","text":"AmiiboFilter"}],"navigatorTitle":[{"text":"AmiiboFilter","kind":"identifier"}],"abstract":[{"text":"A type that contains values to fine-tune a response when requesting amiibo items.","type":"text"}],"identifier":"doc:\/\/AmiiboService\/documentation\/AmiiboService\/AmiiboFilter","type":"topic","title":"AmiiboFilter","role":"symbol"},"doc://AmiiboService/documentation/AmiiboService/AmiiboLiveClient":{"kind":"symbol","url":"\/documentation\/amiiboservice\/amiiboliveclient","fragments":[{"kind":"keyword","text":"struct"},{"kind":"text","text":" "},{"text":"AmiiboLiveClient","kind":"identifier"}],"navigatorTitle":[{"text":"AmiiboLiveClient","kind":"identifier"}],"type":"topic","identifier":"doc:\/\/AmiiboService\/documentation\/AmiiboService\/AmiiboLiveClient","abstract":[{"type":"text","text":"A type that implements a live client to the "},{"type":"reference","isActive":true,"identifier":"https:\/\/www.amiiboapi.org"},{"type":"text","text":" online service."}],"title":"AmiiboLiveClient","role":"symbol"},"doc://AmiiboService/documentation/AmiiboService/GameSeriesFilter":{"url":"\/documentation\/amiiboservice\/gameseriesfilter","kind":"symbol","fragments":[{"kind":"keyword","text":"struct"},{"kind":"text","text":" "},{"text":"GameSeriesFilter","kind":"identifier"}],"navigatorTitle":[{"text":"GameSeriesFilter","kind":"identifier"}],"type":"topic","abstract":[{"type":"text","text":"A type that contains values to fine-tune a response when requesting game series."}],"identifier":"doc:\/\/AmiiboService\/documentation\/AmiiboService\/GameSeriesFilter","title":"GameSeriesFilter","role":"symbol"},"doc://AmiiboService/documentation/AmiiboService/GameSeries":{"role":"symbol","kind":"symbol","identifier":"doc:\/\/AmiiboService\/documentation\/AmiiboService\/GameSeries","fragments":[{"text":"struct","kind":"keyword"},{"text":" ","kind":"text"},{"text":"GameSeries","kind":"identifier"}],"title":"GameSeries","type":"topic","url":"\/documentation\/amiiboservice\/gameseries","navigatorTitle":[{"text":"GameSeries","kind":"identifier"}],"abstract":[{"type":"text","text":"A model that represents a game series."}]},"doc://AmiiboService/documentation/AmiiboService/GameCharacter":{"kind":"symbol","abstract":[{"type":"text","text":"A model that represents a game character."}],"title":"GameCharacter","role":"symbol","fragments":[{"kind":"keyword","text":"struct"},{"kind":"text","text":" "},{"kind":"identifier","text":"GameCharacter"}],"navigatorTitle":[{"text":"GameCharacter","kind":"identifier"}],"url":"\/documentation\/amiiboservice\/gamecharacter","type":"topic","identifier":"doc:\/\/AmiiboService\/documentation\/AmiiboService\/GameCharacter"},"doc://AmiiboService/documentation/AmiiboService/AmiiboService":{"url":"\/documentation\/amiiboservice\/amiiboservice","type":"topic","identifier":"doc:\/\/AmiiboService\/documentation\/AmiiboService\/AmiiboService","role":"symbol","title":"AmiiboService","kind":"symbol","abstract":[{"type":"text","text":"A type that implements the service that uses a client to make calls."}],"fragments":[{"text":"struct","kind":"keyword"},{"text":" ","kind":"text"},{"text":"AmiiboService","kind":"identifier"}],"navigatorTitle":[{"text":"AmiiboService","kind":"identifier"}]},"doc://AmiiboService/documentation/AmiiboService/AmiiboSeriesFilter":{"type":"topic","abstract":[{"text":"A type that contains values to fine-tune a response when requesting amiibo series.","type":"text"}],"navigatorTitle":[{"kind":"identifier","text":"AmiiboSeriesFilter"}],"url":"\/documentation\/amiiboservice\/amiiboseriesfilter","kind":"symbol","identifier":"doc:\/\/AmiiboService\/documentation\/AmiiboService\/AmiiboSeriesFilter","fragments":[{"kind":"keyword","text":"struct"},{"kind":"text","text":" "},{"kind":"identifier","text":"AmiiboSeriesFilter"}],"role":"symbol","title":"AmiiboSeriesFilter"},"doc://AmiiboService/documentation/AmiiboService/AmiiboType":{"role":"symbol","kind":"symbol","identifier":"doc:\/\/AmiiboService\/documentation\/AmiiboService\/AmiiboType","fragments":[{"text":"struct","kind":"keyword"},{"text":" ","kind":"text"},{"text":"AmiiboType","kind":"identifier"}],"url":"\/documentation\/amiiboservice\/amiibotype","title":"AmiiboType","type":"topic","navigatorTitle":[{"kind":"identifier","text":"AmiiboType"}],"abstract":[{"text":"A model that represents an amiibo type.","type":"text"}]},"doc://AmiiboService/documentation/AmiiboService/AmiiboClient":{"navigatorTitle":[{"kind":"identifier","text":"AmiiboClient"}],"fragments":[{"kind":"keyword","text":"protocol"},{"kind":"text","text":" "},{"kind":"identifier","text":"AmiiboClient"}],"identifier":"doc:\/\/AmiiboService\/documentation\/AmiiboService\/AmiiboClient","type":"topic","title":"AmiiboClient","abstract":[{"type":"text","text":"A protocol that defines API clients containing all available endpoints to interact with."}],"kind":"symbol","role":"symbol","url":"\/documentation\/amiiboservice\/amiiboclient"},"doc://AmiiboService/documentation/AmiiboService/AmiiboTypeFilter":{"fragments":[{"text":"struct","kind":"keyword"},{"text":" ","kind":"text"},{"text":"AmiiboTypeFilter","kind":"identifier"}],"navigatorTitle":[{"text":"AmiiboTypeFilter","kind":"identifier"}],"kind":"symbol","role":"symbol","identifier":"doc:\/\/AmiiboService\/documentation\/AmiiboService\/AmiiboTypeFilter","abstract":[{"text":"A type that contains values to fine-tune a response when requesting amiibo types.","type":"text"}],"url":"\/documentation\/amiiboservice\/amiibotypefilter","type":"topic","title":"AmiiboTypeFilter"},"doc://AmiiboService/documentation/AmiiboService/GameCharacterFilter":{"type":"topic","kind":"symbol","identifier":"doc:\/\/AmiiboService\/documentation\/AmiiboService\/GameCharacterFilter","role":"symbol","abstract":[{"text":"A type that contains values to fine-tune a response when requesting game characters.","type":"text"}],"title":"GameCharacterFilter","url":"\/documentation\/amiiboservice\/gamecharacterfilter","fragments":[{"text":"struct","kind":"keyword"},{"text":" ","kind":"text"},{"text":"GameCharacterFilter","kind":"identifier"}],"navigatorTitle":[{"text":"GameCharacterFilter","kind":"identifier"}]}}}