1 line
20 KiB
JSON
1 line
20 KiB
JSON
{"sections":[],"hierarchy":{"paths":[[]]},"topicSections":[{"identifiers":["doc:\/\/AmiiboService\/documentation\/AmiiboService\/AmiiboService"],"title":"Service","anchor":"Service"},{"identifiers":["doc:\/\/AmiiboService\/documentation\/AmiiboService\/AmiiboClient","doc:\/\/AmiiboService\/documentation\/AmiiboService\/AmiiboLiveClient"],"anchor":"Clients","title":"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"],"anchor":"Models","title":"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"],"anchor":"Filters","title":"Filters"},{"identifiers":["doc:\/\/AmiiboService\/documentation\/AmiiboService\/AmiiboServiceError"],"anchor":"Errors","title":"Errors"}],"identifier":{"url":"doc:\/\/AmiiboService\/documentation\/AmiiboService","interfaceLanguage":"swift"},"abstract":[{"type":"text","text":"A library that provides everything the developer needs to interact with the "},{"type":"strong","inlineContent":[{"text":"Amiibo API","type":"text"}]},{"type":"text","text":" backend service."}],"schemaVersion":{"major":0,"patch":0,"minor":3},"kind":"symbol","metadata":{"title":"AmiiboService","roleHeading":"Framework","symbolKind":"module","modules":[{"name":"AmiiboService"}],"externalID":"AmiiboService","role":"collection"},"variants":[{"paths":["\/documentation\/amiiboservice"],"traits":[{"interfaceLanguage":"swift"}]}],"primaryContentSections":[{"content":[{"type":"heading","level":2,"anchor":"Overview","text":"Overview"},{"type":"paragraph","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"},{"type":"reference","identifier":"https:\/\/www.amiiboapi.org","isActive":true},{"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":[{"text":"models","type":"text"}]},{"type":"text","text":", "},{"type":"emphasis","inlineContent":[{"type":"text","text":"filters"}]},{"type":"text","text":", "},{"type":"emphasis","inlineContent":[{"text":"errors","type":"text"}]},{"type":"text","text":" and "},{"type":"emphasis","inlineContent":[{"text":"interfaces","type":"text"}]},{"type":"text","text":" types that might be needed during implementation."}]},{"type":"heading","level":2,"anchor":"Design","text":"Design"},{"type":"paragraph","inlineContent":[{"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":"text"},{"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"}]},{"type":"heading","level":2,"anchor":"Installation","text":"Installation"},{"type":"paragraph","inlineContent":[{"text":"To use the ","type":"text"},{"type":"codeVoice","code":"AmiiboService"},{"text":" library with your package, then add it as a dependency in the ","type":"text"},{"type":"codeVoice","code":"Package.swift"},{"text":" file:","type":"text"}]},{"type":"codeListing","code":["let package = Package("," \/\/ name, platforms, products, etc."," dependencies: ["," .package(url: \"https:\/\/github.com\/rock-n-code\/amiibo-service\", from: \"1.4.2\"),"," \/\/ other dependencies"," ],"," targets: ["," .target("," name: \"SomeTarget\", "," dependencies: ["," .product(name: \"AmiiboService\", package: \"amiibo-service\"),"," ]"," )"," \/\/ other targets"," ]",")"],"syntax":"swift"},{"type":"paragraph","inlineContent":[{"text":"It is also possible to use the ","type":"text"},{"type":"codeVoice","code":"AmiiboService"},{"text":" library with your app in Xcode, then add it as a dependency in your Xcode project.","type":"text"}]},{"type":"aside","content":[{"inlineContent":[{"type":"text","text":"Swift 5.10 or higher is required in order to compile this library."}],"type":"paragraph"}],"style":"important","name":"Important"},{"type":"heading","level":2,"anchor":"Usage","text":"Usage"},{"type":"paragraph","inlineContent":[{"text":"Create an ","type":"text"},{"isActive":true,"identifier":"doc:\/\/AmiiboService\/documentation\/AmiiboService\/AmiiboService","type":"reference"},{"text":" instance and call any of its endpoints. Each endpoint accepts an optional filter and, when omitted, returns the full set of results:","type":"text"}]},{"type":"codeListing","code":["import AmiiboService","","let service = AmiiboService()","","\/\/ Fetch all amiibos","let amiibos = try await service.getAmiibos()","","\/\/ Fetch amiibos filtered by name","let zeldaAmiibos = try await service.getAmiibos(.init(name: \"zelda\"))","","\/\/ Fetch amiibo series, types, game characters, and game series","let series = try await service.getAmiiboSeries()","let types = try await service.getAmiiboTypes()","let characters = try await service.getGameCharacters()","let gameSeries = try await service.getGameSeries()","","\/\/ Fetch the last updated timestamp","let lastUpdated = try await service.getLastUpdated()"],"syntax":"swift"},{"type":"heading","level":2,"anchor":"Caching","text":"Caching"},{"type":"paragraph","inlineContent":[{"text":"The ","type":"text"},{"overridingTitleInlineContent":[{"type":"text","text":"Amiibo API"}],"isActive":true,"overridingTitle":"Amiibo API","identifier":"https:\/\/www.amiiboapi.org","type":"reference"},{"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":"text"}]},{"type":"heading","level":3,"anchor":"URLCache-on-the-transport-layer","text":"URLCache on the transport layer"},{"type":"paragraph","inlineContent":[{"text":"Pass a custom ","type":"text"},{"type":"codeVoice","code":"URLSessionTransport"},{"text":" with a cache-configured ","type":"text"},{"type":"codeVoice","code":"URLSession"},{"text":" to ","type":"text"},{"isActive":true,"identifier":"doc:\/\/AmiiboService\/documentation\/AmiiboService\/AmiiboLiveClient","type":"reference"},{"text":":","type":"text"}]},{"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)",")"],"syntax":"swift"},{"type":"paragraph","inlineContent":[{"text":"This leverages HTTP cache headers from the server and persists cached responses to disk.","type":"text"}]},{"type":"heading","level":3,"anchor":"Application-level-caching","text":"Application-level caching"},{"type":"paragraph","inlineContent":[{"text":"Alternatively, cache the results returned by ","type":"text"},{"isActive":true,"identifier":"doc:\/\/AmiiboService\/documentation\/AmiiboService\/AmiiboService","type":"reference"},{"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":"text"}]},{"type":"heading","level":2,"anchor":"Testing","text":"Testing"},{"type":"paragraph","inlineContent":[{"text":"The ","type":"text"},{"isActive":true,"identifier":"doc:\/\/AmiiboService\/documentation\/AmiiboService\/AmiiboClient","type":"reference"},{"text":" protocol enables creating custom mock clients for testing, eliminating the need for network calls in unit tests. Conform to ","type":"text"},{"isActive":true,"identifier":"doc:\/\/AmiiboService\/documentation\/AmiiboService\/AmiiboClient","type":"reference"},{"text":" and return stubbed data or throw ","type":"text"},{"isActive":true,"identifier":"doc:\/\/AmiiboService\/documentation\/AmiiboService\/AmiiboServiceError","type":"reference"},{"text":" errors to verify your application’s behavior:","type":"text"}]},{"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())"],"syntax":"swift"},{"type":"paragraph","inlineContent":[{"type":"text","text":"Inject the mock client into "},{"type":"reference","identifier":"doc:\/\/AmiiboService\/documentation\/AmiiboService\/AmiiboService","isActive":true},{"type":"text","text":" via its "},{"type":"reference","identifier":"doc:\/\/AmiiboService\/documentation\/AmiiboService\/AmiiboService\/init(client:)","isActive":true},{"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":"heading","level":2,"anchor":"Tasks","text":"Tasks"},{"type":"paragraph","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 "},{"type":"codeVoice","code":"Terminal"},{"type":"text","text":" application."}]},{"type":"aside","content":[{"type":"paragraph","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"}]}],"style":"tip","name":"Tip"},{"type":"codeListing","code":["$ make"],"syntax":"bash"}],"kind":"content"}],"references":{"doc://AmiiboService/documentation/AmiiboService/AmiiboTypeFilter":{"fragments":[{"kind":"keyword","text":"struct"},{"text":" ","kind":"text"},{"kind":"identifier","text":"AmiiboTypeFilter"}],"title":"AmiiboTypeFilter","identifier":"doc:\/\/AmiiboService\/documentation\/AmiiboService\/AmiiboTypeFilter","abstract":[{"text":"A type that contains values to fine-tune a response when requesting amiibo types.","type":"text"}],"kind":"symbol","role":"symbol","type":"topic","url":"\/documentation\/amiiboservice\/amiibotypefilter","navigatorTitle":[{"kind":"identifier","text":"AmiiboTypeFilter"}]},"doc://AmiiboService/documentation/AmiiboService/GameCharacterFilter":{"identifier":"doc:\/\/AmiiboService\/documentation\/AmiiboService\/GameCharacterFilter","role":"symbol","title":"GameCharacterFilter","fragments":[{"text":"struct","kind":"keyword"},{"text":" ","kind":"text"},{"text":"GameCharacterFilter","kind":"identifier"}],"kind":"symbol","abstract":[{"text":"A type that contains values to fine-tune a response when requesting game characters.","type":"text"}],"navigatorTitle":[{"text":"GameCharacterFilter","kind":"identifier"}],"type":"topic","url":"\/documentation\/amiiboservice\/gamecharacterfilter"},"doc://AmiiboService/documentation/AmiiboService":{"title":"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":[{"text":"Amiibo API","type":"text"}]},{"text":" backend service.","type":"text"}],"kind":"symbol","role":"collection","type":"topic","url":"\/documentation\/amiiboservice"},"doc://AmiiboService/documentation/AmiiboService/GameCharacter":{"fragments":[{"text":"struct","kind":"keyword"},{"text":" ","kind":"text"},{"text":"GameCharacter","kind":"identifier"}],"title":"GameCharacter","identifier":"doc:\/\/AmiiboService\/documentation\/AmiiboService\/GameCharacter","abstract":[{"type":"text","text":"A model that represents a game character."}],"kind":"symbol","role":"symbol","type":"topic","url":"\/documentation\/amiiboservice\/gamecharacter","navigatorTitle":[{"text":"GameCharacter","kind":"identifier"}]},"doc://AmiiboService/documentation/AmiiboService/GameSeries":{"fragments":[{"text":"struct","kind":"keyword"},{"text":" ","kind":"text"},{"text":"GameSeries","kind":"identifier"}],"title":"GameSeries","identifier":"doc:\/\/AmiiboService\/documentation\/AmiiboService\/GameSeries","abstract":[{"type":"text","text":"A model that represents a game series."}],"kind":"symbol","role":"symbol","type":"topic","url":"\/documentation\/amiiboservice\/gameseries","navigatorTitle":[{"text":"GameSeries","kind":"identifier"}]},"doc://AmiiboService/documentation/AmiiboService/AmiiboService/init(client:)":{"fragments":[{"kind":"identifier","text":"init"},{"kind":"text","text":"("},{"kind":"externalParam","text":"client"},{"kind":"text","text":": "},{"kind":"keyword","text":"some"},{"kind":"text","text":" "},{"preciseIdentifier":"s:13AmiiboService0A6ClientP","kind":"typeIdentifier","text":"AmiiboClient"},{"kind":"text","text":")"}],"title":"init(client:)","identifier":"doc:\/\/AmiiboService\/documentation\/AmiiboService\/AmiiboService\/init(client:)","abstract":[{"text":"Initializes this service with a specific client type.","type":"text"}],"kind":"symbol","role":"symbol","type":"topic","url":"\/documentation\/amiiboservice\/amiiboservice\/init(client:)"},"doc://AmiiboService/documentation/AmiiboService/Amiibo":{"navigatorTitle":[{"text":"Amiibo","kind":"identifier"}],"url":"\/documentation\/amiiboservice\/amiibo","kind":"symbol","identifier":"doc:\/\/AmiiboService\/documentation\/AmiiboService\/Amiibo","fragments":[{"text":"struct","kind":"keyword"},{"text":" ","kind":"text"},{"text":"Amiibo","kind":"identifier"}],"role":"symbol","abstract":[{"text":"A model that represents an amiibo.","type":"text"}],"type":"topic","title":"Amiibo"},"doc://AmiiboService/documentation/AmiiboService/AmiiboType":{"fragments":[{"text":"struct","kind":"keyword"},{"text":" ","kind":"text"},{"text":"AmiiboType","kind":"identifier"}],"title":"AmiiboType","identifier":"doc:\/\/AmiiboService\/documentation\/AmiiboService\/AmiiboType","abstract":[{"text":"A model that represents an amiibo type.","type":"text"}],"kind":"symbol","role":"symbol","type":"topic","url":"\/documentation\/amiiboservice\/amiibotype","navigatorTitle":[{"text":"AmiiboType","kind":"identifier"}]},"doc://AmiiboService/documentation/AmiiboService/AmiiboFilter":{"identifier":"doc:\/\/AmiiboService\/documentation\/AmiiboService\/AmiiboFilter","type":"topic","title":"AmiiboFilter","abstract":[{"text":"A type that contains values to fine-tune a response when requesting amiibo items.","type":"text"}],"role":"symbol","navigatorTitle":[{"kind":"identifier","text":"AmiiboFilter"}],"kind":"symbol","url":"\/documentation\/amiiboservice\/amiibofilter","fragments":[{"text":"struct","kind":"keyword"},{"text":" ","kind":"text"},{"text":"AmiiboFilter","kind":"identifier"}]},"doc://AmiiboService/documentation/AmiiboService/AmiiboServiceError":{"navigatorTitle":[{"text":"AmiiboServiceError","kind":"identifier"}],"url":"\/documentation\/amiiboservice\/amiiboserviceerror","kind":"symbol","identifier":"doc:\/\/AmiiboService\/documentation\/AmiiboService\/AmiiboServiceError","fragments":[{"text":"enum","kind":"keyword"},{"text":" ","kind":"text"},{"text":"AmiiboServiceError","kind":"identifier"}],"role":"symbol","abstract":[{"text":"A representation of all the possible errors that the ","type":"text"},{"isActive":true,"type":"reference","identifier":"doc:\/\/AmiiboService\/documentation\/AmiiboService\/AmiiboService"},{"text":" service could throw.","type":"text"}],"title":"AmiiboServiceError","type":"topic"},"doc://AmiiboService/documentation/AmiiboService/GameSeriesFilter":{"fragments":[{"text":"struct","kind":"keyword"},{"text":" ","kind":"text"},{"text":"GameSeriesFilter","kind":"identifier"}],"title":"GameSeriesFilter","identifier":"doc:\/\/AmiiboService\/documentation\/AmiiboService\/GameSeriesFilter","abstract":[{"type":"text","text":"A type that contains values to fine-tune a response when requesting game series."}],"kind":"symbol","role":"symbol","type":"topic","url":"\/documentation\/amiiboservice\/gameseriesfilter","navigatorTitle":[{"text":"GameSeriesFilter","kind":"identifier"}]},"doc://AmiiboService/documentation/AmiiboService/AmiiboClient":{"identifier":"doc:\/\/AmiiboService\/documentation\/AmiiboService\/AmiiboClient","role":"symbol","title":"AmiiboClient","fragments":[{"kind":"keyword","text":"protocol"},{"kind":"text","text":" "},{"kind":"identifier","text":"AmiiboClient"}],"kind":"symbol","abstract":[{"text":"A protocol that defines API clients containing all available endpoints to interact with.","type":"text"}],"navigatorTitle":[{"kind":"identifier","text":"AmiiboClient"}],"type":"topic","url":"\/documentation\/amiiboservice\/amiiboclient"},"doc://AmiiboService/documentation/AmiiboService/AmiiboSeriesFilter":{"fragments":[{"kind":"keyword","text":"struct"},{"kind":"text","text":" "},{"kind":"identifier","text":"AmiiboSeriesFilter"}],"title":"AmiiboSeriesFilter","identifier":"doc:\/\/AmiiboService\/documentation\/AmiiboService\/AmiiboSeriesFilter","abstract":[{"text":"A type that contains values to fine-tune a response when requesting amiibo series.","type":"text"}],"kind":"symbol","role":"symbol","type":"topic","url":"\/documentation\/amiiboservice\/amiiboseriesfilter","navigatorTitle":[{"kind":"identifier","text":"AmiiboSeriesFilter"}]},"https://www.amiiboapi.org":{"type":"link","titleInlineContent":[{"text":"Amiibo API","type":"text"}],"title":"Amiibo API","url":"https:\/\/www.amiiboapi.org","identifier":"https:\/\/www.amiiboapi.org"},"doc://AmiiboService/documentation/AmiiboService/AmiiboLiveClient":{"identifier":"doc:\/\/AmiiboService\/documentation\/AmiiboService\/AmiiboLiveClient","role":"symbol","title":"AmiiboLiveClient","fragments":[{"kind":"keyword","text":"struct"},{"kind":"text","text":" "},{"kind":"identifier","text":"AmiiboLiveClient"}],"kind":"symbol","abstract":[{"text":"A type that implements a live client to the ","type":"text"},{"isActive":true,"identifier":"https:\/\/www.amiiboapi.org","type":"reference"},{"text":" online service.","type":"text"}],"navigatorTitle":[{"kind":"identifier","text":"AmiiboLiveClient"}],"type":"topic","url":"\/documentation\/amiiboservice\/amiiboliveclient"},"doc://AmiiboService/documentation/AmiiboService/AmiiboSeries":{"fragments":[{"text":"struct","kind":"keyword"},{"text":" ","kind":"text"},{"text":"AmiiboSeries","kind":"identifier"}],"title":"AmiiboSeries","identifier":"doc:\/\/AmiiboService\/documentation\/AmiiboService\/AmiiboSeries","abstract":[{"type":"text","text":"A model that represents an amiibo series."}],"kind":"symbol","role":"symbol","type":"topic","url":"\/documentation\/amiiboservice\/amiiboseries","navigatorTitle":[{"text":"AmiiboSeries","kind":"identifier"}]},"doc://AmiiboService/documentation/AmiiboService/AmiiboService":{"navigatorTitle":[{"kind":"identifier","text":"AmiiboService"}],"url":"\/documentation\/amiiboservice\/amiiboservice","kind":"symbol","identifier":"doc:\/\/AmiiboService\/documentation\/AmiiboService\/AmiiboService","fragments":[{"text":"struct","kind":"keyword"},{"text":" ","kind":"text"},{"text":"AmiiboService","kind":"identifier"}],"role":"symbol","abstract":[{"text":"A type that implements the service that uses a client to make calls.","type":"text"}],"title":"AmiiboService","type":"topic"}}} |