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