1 line
21 KiB
JSON
1 line
21 KiB
JSON
{"primaryContentSections":[{"kind":"content","content":[{"level":2,"type":"heading","anchor":"Overview","text":"Overview"},{"type":"paragraph","inlineContent":[{"type":"codeVoice","code":"AmiiboService"},{"type":"text","text":" fetches data from the "},{"type":"reference","identifier":"https:\/\/www.amiiboapi.org","isActive":true},{"type":"text","text":" and returns it as Swift models."}]},{"type":"paragraph","inlineContent":[{"type":"text","text":"The library does not expose a generated client that maps one-to-one to the REST endpoints. Instead, "},{"type":"reference","identifier":"doc:\/\/AmiiboService\/documentation\/AmiiboService\/AmiiboService","isActive":true},{"type":"text","text":" offers one method per resource, takes a typed filter, returns sorted models, and throws a single "},{"type":"reference","identifier":"doc:\/\/AmiiboService\/documentation\/AmiiboService\/AmiiboServiceError","isActive":true},{"type":"text","text":" type."}]},{"level":2,"type":"heading","anchor":"Installation","text":"Installation"},{"type":"paragraph","inlineContent":[{"type":"text","text":"Add the package and the "},{"type":"codeVoice","code":"AmiiboService"},{"type":"text","text":" product to "},{"type":"codeVoice","code":"Package.swift"},{"type":"text","text":":"}]},{"type":"codeListing","syntax":"swift","code":["let package = Package("," \/\/ name, platforms, products, etc."," dependencies: ["," .package(url: \"https:\/\/github.com\/rock-n-code\/amiibo-service\", from: \"2.0.0\"),"," ],"," targets: ["," .target("," name: \"SomeTarget\","," dependencies: ["," .product(name: \"AmiiboService\", package: \"amiibo-service\"),"," ]"," ),"," ]",")"]},{"type":"paragraph","inlineContent":[{"type":"text","text":"In Xcode, add the package URL under "},{"inlineContent":[{"type":"text","text":"File › Add Package Dependencies…"}],"type":"strong"},{"type":"text","text":"."}]},{"name":"Important","type":"aside","content":[{"inlineContent":[{"type":"text","text":"Requires Swift 6.2 or later, and iOS 13, macOS 10.15, tvOS 13, visionOS 1, or watchOS 6 or later."}],"type":"paragraph"}],"style":"important"},{"level":2,"type":"heading","anchor":"Usage","text":"Usage"},{"type":"paragraph","inlineContent":[{"type":"text","text":"Create an "},{"type":"reference","identifier":"doc:\/\/AmiiboService\/documentation\/AmiiboService\/AmiiboService","isActive":true},{"type":"text","text":" and call its methods. When you omit the filter, the method returns every item:"}]},{"type":"codeListing","syntax":"swift","code":["import AmiiboService","","let service = AmiiboService()","","\/\/ All amiibos","let amiibos = try await service.getAmiibos()","","\/\/ Amiibos whose name contains \"zelda\"","let zeldaAmiibos = try await service.getAmiibos(.init(name: \"zelda\"))","","\/\/ 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()","","\/\/ Date of the last data update (UTC)","let lastUpdated = try await service.getLastUpdated()"]},{"type":"paragraph","inlineContent":[{"type":"text","text":"Results are sorted in ascending order by "},{"type":"reference","identifier":"doc:\/\/AmiiboService\/documentation\/AmiiboService\/Amiibo\/identifier","isActive":true},{"type":"text","text":" or by "},{"type":"codeVoice","code":"key"},{"type":"text","text":"."}]},{"level":2,"type":"heading","anchor":"Error-handling","text":"Error handling"},{"type":"paragraph","inlineContent":[{"type":"text","text":"Every method throws "},{"type":"reference","identifier":"doc:\/\/AmiiboService\/documentation\/AmiiboService\/AmiiboServiceError","isActive":true},{"type":"text","text":". When nothing matches, "},{"type":"reference","identifier":"doc:\/\/AmiiboService\/documentation\/AmiiboService\/AmiiboService\/getAmiibos(_:)","isActive":true},{"type":"text","text":" returns an empty array, while the other list methods throw "},{"type":"reference","identifier":"doc:\/\/AmiiboService\/documentation\/AmiiboService\/AmiiboServiceError\/notFound","isActive":true},{"type":"text","text":":"}]},{"type":"codeListing","syntax":"swift","code":["do throws(AmiiboServiceError) {"," let series = try await service.getAmiiboSeries(.init(key: \"0x01\"))","} catch .notFound {"," \/\/ No amiibo series has this key.","} catch {"," \/\/ .badRequest, .cancelled, .decoding, .notAvailable, .undocumented, or .unknown","}"]},{"level":2,"type":"heading","anchor":"Caching","text":"Caching"},{"type":"paragraph","inlineContent":[{"type":"text","text":"The library has no built-in cache. The Amiibo API asks regular consumers to cache responses."}]},{"type":"paragraph","inlineContent":[{"type":"text","text":"To cache at the HTTP level, give "},{"type":"reference","identifier":"doc:\/\/AmiiboService\/documentation\/AmiiboService\/AmiiboLiveClient","isActive":true},{"type":"text","text":" a transport backed by a "},{"type":"codeVoice","code":"URLCache"},{"type":"text","text":". The cache follows the server’s cache headers:"}]},{"type":"codeListing","syntax":"swift","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":"You can also store the returned models in your own application storage."}]},{"level":2,"type":"heading","anchor":"Testing","text":"Testing"},{"type":"paragraph","inlineContent":[{"type":"text","text":"To test without network access, pass a mock "},{"type":"reference","identifier":"doc:\/\/AmiiboService\/documentation\/AmiiboService\/AmiiboClient","isActive":true},{"type":"text","text":" to "},{"type":"reference","identifier":"doc:\/\/AmiiboService\/documentation\/AmiiboService\/AmiiboService\/init(client:)","isActive":true},{"type":"text","text":". The mock can return stub data or throw "},{"type":"reference","identifier":"doc:\/\/AmiiboService\/documentation\/AmiiboService\/AmiiboServiceError","isActive":true},{"type":"text","text":" values. "},{"type":"reference","identifier":"doc:\/\/AmiiboService\/documentation\/AmiiboService\/AmiiboClient","isActive":true},{"type":"text","text":" refines "},{"type":"codeVoice","code":"Sendable"},{"type":"text","text":", so the mock must be "},{"type":"codeVoice","code":"Sendable"},{"type":"text","text":", too:"}]},{"type":"codeListing","syntax":"swift","code":["import AmiiboService","","struct MockClient: AmiiboClient {"," var error: AmiiboServiceError?",""," func getAmiibos("," by filter: AmiiboFilter"," ) async throws(AmiiboServiceError) -> [Amiibo] {"," if let error { throw error }"," return []"," }",""," \/\/ Implement the remaining requirements...","}","","let service = AmiiboService(client: MockClient())"]}]}],"sections":[],"topicSections":[{"identifiers":["doc:\/\/AmiiboService\/documentation\/AmiiboService\/AmiiboService"],"anchor":"Service","title":"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"}],"variants":[{"traits":[{"interfaceLanguage":"swift"}],"paths":["\/documentation\/amiiboservice"]}],"schemaVersion":{"major":0,"minor":3,"patch":0},"metadata":{"roleHeading":"Framework","modules":[{"name":"AmiiboService"}],"role":"collection","title":"AmiiboService","externalID":"AmiiboService","symbolKind":"module"},"identifier":{"interfaceLanguage":"swift","url":"doc:\/\/AmiiboService\/documentation\/AmiiboService"},"hierarchy":{"paths":[[]]},"kind":"symbol","abstract":[{"type":"text","text":"A Swift client for the Amiibo API."}],"references":{"https://www.amiiboapi.org":{"title":"Amiibo API","identifier":"https:\/\/www.amiiboapi.org","url":"https:\/\/www.amiiboapi.org","type":"link","titleInlineContent":[{"type":"text","text":"Amiibo API"}]},"doc://AmiiboService/documentation/AmiiboService/AmiiboService/init(client:)":{"title":"init(client:)","role":"symbol","url":"\/documentation\/amiiboservice\/amiiboservice\/init(client:)","kind":"symbol","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"}],"type":"topic","identifier":"doc:\/\/AmiiboService\/documentation\/AmiiboService\/AmiiboService\/init(client:)","abstract":[{"type":"text","text":"Initializes this service with a client."}]},"doc://AmiiboService/documentation/AmiiboService/Amiibo/tail":{"title":"tail","role":"symbol","url":"\/documentation\/amiiboservice\/amiibo\/tail","kind":"symbol","fragments":[{"kind":"keyword","text":"let"},{"kind":"text","text":" "},{"kind":"identifier","text":"tail"},{"kind":"text","text":": "},{"kind":"typeIdentifier","text":"String","preciseIdentifier":"s:SS"}],"type":"topic","abstract":[{"type":"text","text":"The last 8 hexadecimal characters of the amiibo identifier."}],"identifier":"doc:\/\/AmiiboService\/documentation\/AmiiboService\/Amiibo\/tail"},"doc://AmiiboService/documentation/AmiiboService/AmiiboType":{"navigatorTitle":[{"kind":"identifier","text":"AmiiboType"}],"title":"AmiiboType","url":"\/documentation\/amiiboservice\/amiibotype","role":"symbol","type":"topic","fragments":[{"kind":"keyword","text":"struct"},{"text":" ","kind":"text"},{"text":"AmiiboType","kind":"identifier"}],"identifier":"doc:\/\/AmiiboService\/documentation\/AmiiboService\/AmiiboType","kind":"symbol","abstract":[{"text":"A model that represents an amiibo type.","type":"text"}]},"doc://AmiiboService/documentation/AmiiboService/AmiiboServiceError":{"title":"AmiiboServiceError","kind":"symbol","url":"\/documentation\/amiiboservice\/amiiboserviceerror","role":"symbol","fragments":[{"kind":"keyword","text":"enum"},{"kind":"text","text":" "},{"kind":"identifier","text":"AmiiboServiceError"}],"identifier":"doc:\/\/AmiiboService\/documentation\/AmiiboService\/AmiiboServiceError","navigatorTitle":[{"kind":"identifier","text":"AmiiboServiceError"}],"type":"topic","abstract":[{"text":"An error thrown by ","type":"text"},{"identifier":"doc:\/\/AmiiboService\/documentation\/AmiiboService\/AmiiboService","type":"reference","isActive":true},{"text":" and ","type":"text"},{"isActive":true,"type":"reference","identifier":"doc:\/\/AmiiboService\/documentation\/AmiiboService\/AmiiboClient"},{"text":" methods.","type":"text"}]},"doc://AmiiboService/documentation/AmiiboService/Amiibo/head":{"kind":"symbol","title":"head","url":"\/documentation\/amiiboservice\/amiibo\/head","role":"symbol","fragments":[{"kind":"keyword","text":"let"},{"kind":"text","text":" "},{"kind":"identifier","text":"head"},{"kind":"text","text":": "},{"kind":"typeIdentifier","preciseIdentifier":"s:SS","text":"String"}],"identifier":"doc:\/\/AmiiboService\/documentation\/AmiiboService\/Amiibo\/head","type":"topic","abstract":[{"text":"The first 8 hexadecimal characters of the amiibo identifier.","type":"text"}]},"doc://AmiiboService/documentation/AmiiboService/GameCharacterFilter":{"title":"GameCharacterFilter","fragments":[{"kind":"keyword","text":"struct"},{"kind":"text","text":" "},{"kind":"identifier","text":"GameCharacterFilter"}],"abstract":[{"text":"A filter for game character requests.","type":"text"}],"kind":"symbol","url":"\/documentation\/amiiboservice\/gamecharacterfilter","navigatorTitle":[{"text":"GameCharacterFilter","kind":"identifier"}],"type":"topic","role":"symbol","identifier":"doc:\/\/AmiiboService\/documentation\/AmiiboService\/GameCharacterFilter"},"doc://AmiiboService/documentation/AmiiboService/AmiiboFilter":{"identifier":"doc:\/\/AmiiboService\/documentation\/AmiiboService\/AmiiboFilter","kind":"symbol","role":"symbol","fragments":[{"kind":"keyword","text":"struct"},{"kind":"text","text":" "},{"kind":"identifier","text":"AmiiboFilter"}],"type":"topic","abstract":[{"type":"text","text":"A filter for amiibo requests."}],"title":"AmiiboFilter","navigatorTitle":[{"kind":"identifier","text":"AmiiboFilter"}],"url":"\/documentation\/amiiboservice\/amiibofilter"},"doc://AmiiboService/documentation/AmiiboService/AmiiboSeriesFilter":{"title":"AmiiboSeriesFilter","role":"symbol","url":"\/documentation\/amiiboservice\/amiiboseriesfilter","navigatorTitle":[{"kind":"identifier","text":"AmiiboSeriesFilter"}],"kind":"symbol","fragments":[{"kind":"keyword","text":"struct"},{"kind":"text","text":" "},{"kind":"identifier","text":"AmiiboSeriesFilter"}],"type":"topic","abstract":[{"type":"text","text":"A filter for amiibo series requests."}],"identifier":"doc:\/\/AmiiboService\/documentation\/AmiiboService\/AmiiboSeriesFilter"},"doc://AmiiboService/documentation/AmiiboService":{"title":"AmiiboService","role":"collection","url":"\/documentation\/amiiboservice","kind":"symbol","type":"topic","identifier":"doc:\/\/AmiiboService\/documentation\/AmiiboService","abstract":[{"type":"text","text":"A Swift client for the Amiibo API."}]},"doc://AmiiboService/documentation/AmiiboService/AmiiboClient":{"navigatorTitle":[{"text":"AmiiboClient","kind":"identifier"}],"title":"AmiiboClient","url":"\/documentation\/amiiboservice\/amiiboclient","role":"symbol","type":"topic","fragments":[{"kind":"keyword","text":"protocol"},{"kind":"text","text":" "},{"kind":"identifier","text":"AmiiboClient"}],"identifier":"doc:\/\/AmiiboService\/documentation\/AmiiboService\/AmiiboClient","kind":"symbol","abstract":[{"type":"text","text":"A protocol that defines a client that fetches data from the Amiibo API."}]},"doc://AmiiboService/documentation/AmiiboService/AmiiboService/getAmiibos(_:)":{"title":"getAmiibos(_:)","role":"symbol","url":"\/documentation\/amiiboservice\/amiiboservice\/getamiibos(_:)","kind":"symbol","fragments":[{"kind":"keyword","text":"func"},{"kind":"text","text":" "},{"kind":"identifier","text":"getAmiibos"},{"kind":"text","text":"("},{"kind":"typeIdentifier","text":"AmiiboFilter","preciseIdentifier":"s:13AmiiboService0A6FilterV"},{"kind":"text","text":") "},{"kind":"keyword","text":"async"},{"kind":"text","text":" "},{"kind":"keyword","text":"throws"},{"kind":"text","text":"("},{"kind":"typeIdentifier","text":"AmiiboServiceError","preciseIdentifier":"s:13AmiiboService0aB5ErrorO"},{"kind":"text","text":") -> ["},{"kind":"typeIdentifier","text":"Amiibo","preciseIdentifier":"s:13AmiiboService0A0V"},{"kind":"text","text":"]"}],"type":"topic","abstract":[{"type":"text","text":"Gets a list of amiibo items based on a given filter."}],"identifier":"doc:\/\/AmiiboService\/documentation\/AmiiboService\/AmiiboService\/getAmiibos(_:)"},"doc://AmiiboService/documentation/AmiiboService/GameSeriesFilter":{"title":"GameSeriesFilter","kind":"symbol","url":"\/documentation\/amiiboservice\/gameseriesfilter","role":"symbol","fragments":[{"kind":"keyword","text":"struct"},{"kind":"text","text":" "},{"kind":"identifier","text":"GameSeriesFilter"}],"identifier":"doc:\/\/AmiiboService\/documentation\/AmiiboService\/GameSeriesFilter","navigatorTitle":[{"kind":"identifier","text":"GameSeriesFilter"}],"type":"topic","abstract":[{"type":"text","text":"A filter for game series requests."}]},"doc://AmiiboService/documentation/AmiiboService/GameSeries":{"navigatorTitle":[{"kind":"identifier","text":"GameSeries"}],"title":"GameSeries","url":"\/documentation\/amiiboservice\/gameseries","role":"symbol","type":"topic","fragments":[{"kind":"keyword","text":"struct"},{"kind":"text","text":" "},{"kind":"identifier","text":"GameSeries"}],"identifier":"doc:\/\/AmiiboService\/documentation\/AmiiboService\/GameSeries","kind":"symbol","abstract":[{"type":"text","text":"A model that represents a game series."}]},"doc://AmiiboService/documentation/AmiiboService/GameCharacter":{"title":"GameCharacter","role":"symbol","url":"\/documentation\/amiiboservice\/gamecharacter","navigatorTitle":[{"kind":"identifier","text":"GameCharacter"}],"kind":"symbol","fragments":[{"kind":"keyword","text":"struct"},{"kind":"text","text":" "},{"kind":"identifier","text":"GameCharacter"}],"type":"topic","identifier":"doc:\/\/AmiiboService\/documentation\/AmiiboService\/GameCharacter","abstract":[{"type":"text","text":"A model that represents a game character."}]},"doc://AmiiboService/documentation/AmiiboService/Amiibo":{"abstract":[{"text":"A model that represents an amiibo.","type":"text"}],"identifier":"doc:\/\/AmiiboService\/documentation\/AmiiboService\/Amiibo","title":"Amiibo","role":"symbol","kind":"symbol","fragments":[{"kind":"keyword","text":"struct"},{"kind":"text","text":" "},{"kind":"identifier","text":"Amiibo"}],"type":"topic","navigatorTitle":[{"kind":"identifier","text":"Amiibo"}],"url":"\/documentation\/amiiboservice\/amiibo"},"doc://AmiiboService/documentation/AmiiboService/Amiibo/identifier":{"title":"identifier","role":"symbol","url":"\/documentation\/amiiboservice\/amiibo\/identifier","kind":"symbol","fragments":[{"kind":"keyword","text":"var"},{"kind":"text","text":" "},{"kind":"identifier","text":"identifier"},{"kind":"text","text":": "},{"kind":"typeIdentifier","preciseIdentifier":"s:SS","text":"String"}],"type":"topic","abstract":[{"type":"text","text":"The full 16-character hexadecimal identifier, composed of the "},{"identifier":"doc:\/\/AmiiboService\/documentation\/AmiiboService\/Amiibo\/head","isActive":true,"type":"reference"},{"type":"text","text":" and "},{"identifier":"doc:\/\/AmiiboService\/documentation\/AmiiboService\/Amiibo\/tail","isActive":true,"type":"reference"},{"type":"text","text":"."}],"identifier":"doc:\/\/AmiiboService\/documentation\/AmiiboService\/Amiibo\/identifier"},"doc://AmiiboService/documentation/AmiiboService/AmiiboServiceError/notFound":{"title":"AmiiboServiceError.notFound","url":"\/documentation\/amiiboservice\/amiiboserviceerror\/notfound","role":"symbol","type":"topic","fragments":[{"kind":"keyword","text":"case"},{"kind":"text","text":" "},{"kind":"identifier","text":"notFound"}],"identifier":"doc:\/\/AmiiboService\/documentation\/AmiiboService\/AmiiboServiceError\/notFound","kind":"symbol","abstract":[{"type":"text","text":"No results were found matching the given filter criteria."}]},"doc://AmiiboService/documentation/AmiiboService/AmiiboService":{"title":"AmiiboService","role":"symbol","url":"\/documentation\/amiiboservice\/amiiboservice","navigatorTitle":[{"kind":"identifier","text":"AmiiboService"}],"kind":"symbol","fragments":[{"kind":"keyword","text":"struct"},{"kind":"text","text":" "},{"kind":"identifier","text":"AmiiboService"}],"type":"topic","identifier":"doc:\/\/AmiiboService\/documentation\/AmiiboService\/AmiiboService","abstract":[{"type":"text","text":"The entry point for fetching data from the Amiibo API."}]},"doc://AmiiboService/documentation/AmiiboService/AmiiboLiveClient":{"kind":"symbol","title":"AmiiboLiveClient","url":"\/documentation\/amiiboservice\/amiiboliveclient","role":"symbol","fragments":[{"kind":"keyword","text":"struct"},{"kind":"text","text":" "},{"text":"AmiiboLiveClient","kind":"identifier"}],"identifier":"doc:\/\/AmiiboService\/documentation\/AmiiboService\/AmiiboLiveClient","navigatorTitle":[{"kind":"identifier","text":"AmiiboLiveClient"}],"type":"topic","abstract":[{"type":"text","text":"A type that implements a live client to the "},{"identifier":"https:\/\/www.amiiboapi.org","isActive":true,"type":"reference"},{"type":"text","text":" online service."}]},"doc://AmiiboService/documentation/AmiiboService/AmiiboTypeFilter":{"navigatorTitle":[{"kind":"identifier","text":"AmiiboTypeFilter"}],"title":"AmiiboTypeFilter","url":"\/documentation\/amiiboservice\/amiibotypefilter","role":"symbol","type":"topic","fragments":[{"kind":"keyword","text":"struct"},{"kind":"text","text":" "},{"kind":"identifier","text":"AmiiboTypeFilter"}],"kind":"symbol","identifier":"doc:\/\/AmiiboService\/documentation\/AmiiboService\/AmiiboTypeFilter","abstract":[{"type":"text","text":"A filter for amiibo type requests."}]},"doc://AmiiboService/documentation/AmiiboService/AmiiboSeries":{"title":"AmiiboSeries","role":"symbol","url":"\/documentation\/amiiboservice\/amiiboseries","navigatorTitle":[{"kind":"identifier","text":"AmiiboSeries"}],"kind":"symbol","fragments":[{"kind":"keyword","text":"struct"},{"kind":"text","text":" "},{"kind":"identifier","text":"AmiiboSeries"}],"type":"topic","identifier":"doc:\/\/AmiiboService\/documentation\/AmiiboService\/AmiiboSeries","abstract":[{"type":"text","text":"A model that represents an amiibo series."}]}}} |