amiibo-service/AmiiboService.doccarchive/data/documentation/amiiboservice/gettingstarted.json

{"primaryContentSections":[{"kind":"content","content":[{"anchor":"Installing-the-package","level":2,"type":"heading","text":"Installing the package"},{"type":"paragraph","inlineContent":[{"type":"text","text":"It is possible to add this package to other libraries and applications by adding it as a dependency in a "},{"type":"codeVoice","code":"Package.swift"},{"type":"text","text":" file or in a Xcode project, through the "},{"type":"emphasis","inlineContent":[{"type":"text","text":"Package dependencies"}]},{"type":"text","text":" interface."}]},{"type":"paragraph","inlineContent":[{"type":"text","text":"It is also important to highlight that this package has minimum platform requirements that must be taken into account:"}]},{"type":"unorderedList","items":[{"content":[{"type":"paragraph","inlineContent":[{"type":"emphasis","inlineContent":[{"type":"text","text":"iOS 15.0 or higher"}]},{"type":"text","text":";"}]}]},{"content":[{"type":"paragraph","inlineContent":[{"type":"emphasis","inlineContent":[{"type":"text","text":"macOS 12.0 or higher"}]},{"type":"text","text":";"}]}]},{"content":[{"type":"paragraph","inlineContent":[{"type":"emphasis","inlineContent":[{"type":"text","text":"tvOS 15.0 or higher"}]},{"type":"text","text":";"}]}]},{"content":[{"type":"paragraph","inlineContent":[{"type":"emphasis","inlineContent":[{"type":"text","text":"watchOS 8.0 or higher"}]},{"type":"text","text":"."}]}]}]},{"anchor":"The-Packageswift-file-way","level":3,"type":"heading","text":"The “Package.swift” file way"},{"type":"paragraph","inlineContent":[{"type":"text","text":"In the intended "},{"type":"codeVoice","code":"Package.swift"},{"type":"text","text":" file, it is required to add the dependency, as demonstrated below:"}]},{"type":"codeListing","syntax":"swift","code":["dependencies: [","    \/\/ ...","    .package(url: \"https:\/\/github.com\/rock-n-code\/amiibo-service.git\", from: \"1.0.3\")","    \/\/ ...","],"]},{"type":"paragraph","inlineContent":[{"type":"text","text":"Then it is required to add the package to your target, like this:"}]},{"type":"codeListing","syntax":"swift","code":["targets: [","    .target(","        \/\/ ...","        dependencies: [","            .product(name: \"AmiiboService\", package: \"amiibo-service\")","        ],","        \/\/ ...","    ),","]"]},{"anchor":"The-Package-dependencies-in-Xcode-way","level":3,"type":"heading","text":"The “Package dependencies” in Xcode way"},{"type":"paragraph","inlineContent":[{"type":"text","text":"In an opened Xcode project, it is required to follow these steps to install the package:"}]},{"type":"orderedList","items":[{"content":[{"type":"paragraph","inlineContent":[{"type":"text","text":"click on the Xcode project file in the sidebar to display "},{"type":"emphasis","inlineContent":[{"type":"text","text":"Project"}]},{"type":"text","text":" and "},{"type":"emphasis","inlineContent":[{"type":"text","text":"Targets"}]},{"type":"text","text":";"}]}]},{"content":[{"type":"paragraph","inlineContent":[{"type":"text","text":"select the project under the "},{"type":"emphasis","inlineContent":[{"type":"text","text":"Project"}]},{"type":"text","text":" section to show the "},{"type":"emphasis","inlineContent":[{"type":"text","text":"Info"}]},{"type":"text","text":", "},{"type":"emphasis","inlineContent":[{"type":"text","text":"Build Settings"}]},{"type":"text","text":" and "},{"type":"emphasis","inlineContent":[{"type":"text","text":"Package Dependencies"}]},{"type":"text","text":" options in the center menu just right on top;"}]}]},{"content":[{"type":"paragraph","inlineContent":[{"type":"text","text":"select the "},{"type":"emphasis","inlineContent":[{"type":"text","text":"Package Dependencies"}]},{"type":"text","text":" option to show the defined dependencies of the project;"}]}]},{"content":[{"type":"paragraph","inlineContent":[{"type":"text","text":"press on the "},{"type":"emphasis","inlineContent":[{"type":"text","text":"+"}]},{"type":"text","text":" (plus) button to add dependencies to the project;"}]}]},{"content":[{"type":"paragraph","inlineContent":[{"type":"text","text":"enter the URL "},{"type":"codeVoice","code":"https:\/\/github.com\/rock-n-code\/amiibo-service"},{"type":"text","text":" into the "},{"type":"emphasis","inlineContent":[{"type":"text","text":"Search or Enter Package URL"}]},{"type":"text","text":" located in the upper right corner;"}]}]},{"content":[{"type":"paragraph","inlineContent":[{"type":"text","text":"select the retrieved option;"}]}]},{"content":[{"type":"paragraph","inlineContent":[{"type":"text","text":"define the dependency rule (the "},{"type":"emphasis","inlineContent":[{"type":"text","text":"Up to Next Major Version"}]},{"type":"text","text":" option and the "},{"type":"emphasis","inlineContent":[{"type":"text","text":"1.0.3"}]},{"type":"text","text":" text are recommended);"}]}]},{"content":[{"type":"paragraph","inlineContent":[{"type":"text","text":"select the target to which the dependency will be applied (if required);"}]}]},{"content":[{"type":"paragraph","inlineContent":[{"type":"text","text":"wait for the package to be resolved and included in the project;"}]}]},{"content":[{"type":"paragraph","inlineContent":[{"type":"text","text":"now you should be ready to start using this package!"}]}]}]},{"anchor":"Using-the-service","level":2,"type":"heading","text":"Using the service"},{"type":"paragraph","inlineContent":[{"type":"text","text":"Now that this package is installed in the project, the "},{"type":"reference","isActive":true,"identifier":"doc:\/\/AmiiboService\/documentation\/AmiiboService\/AmiiboService"},{"type":"text","text":" service will be available after importing the package into your source code, like this:"}]},{"type":"codeListing","syntax":"swift","code":["import AmiiboService"]},{"type":"paragraph","inlineContent":[{"type":"text","text":"This service requires a "},{"type":"codeVoice","code":"URLSessionConfiguration"},{"type":"text","text":" instance to initialise, which is included into the "},{"type":"codeVoice","code":"Foundation"},{"type":"text","text":" framework. Although it is possible to initialise the service as simple as this:"}]},{"type":"codeListing","syntax":"swift","code":["private let service = AmiiboService(configuration: .default)"]},{"type":"paragraph","inlineContent":[{"type":"text","text":"It is recommendable to add cache support for the configuration instance before initialising the service with it, especially in case of making regular calls to the remote API service (as recommended by the "},{"type":"reference","isActive":true,"identifier":"https:\/\/www.amiiboapi.com\/docs\/#info"},{"type":"text","text":")."}]},{"type":"paragraph","inlineContent":[{"type":"text","text":"This service provides these following functions, which all basically are meant to be making requests based on a given filter criteria to the remote API, handling the responses, and decoding the retrieved data into models\/entities structs, or throws errors if necessary:"}]},{"type":"unorderedList","items":[{"content":[{"type":"paragraph","inlineContent":[{"type":"reference","isActive":true,"identifier":"doc:\/\/AmiiboService\/documentation\/AmiiboService\/AmiiboService\/amiibos(filter:)"},{"type":"text","text":" that interacts with the respective "},{"type":"reference","isActive":true,"identifier":"https:\/\/www.amiiboapi.com\/docs\/#amiibo"},{"type":"text","text":";"}]}]},{"content":[{"type":"paragraph","inlineContent":[{"type":"reference","isActive":true,"identifier":"doc:\/\/AmiiboService\/documentation\/AmiiboService\/AmiiboService\/amiiboSeries(filter:)"},{"type":"text","text":" that interacts with the respective "},{"type":"reference","isActive":true,"identifier":"https:\/\/www.amiiboapi.com\/docs\/#series"},{"type":"text","text":";"}]}]},{"content":[{"type":"paragraph","inlineContent":[{"type":"reference","isActive":true,"identifier":"doc:\/\/AmiiboService\/documentation\/AmiiboService\/AmiiboService\/amiiboTypes(filter:)"},{"type":"text","text":" that interacts with the respective "},{"type":"reference","isActive":true,"identifier":"https:\/\/www.amiiboapi.com\/docs\/#type"},{"type":"text","text":";"}]}]},{"content":[{"type":"paragraph","inlineContent":[{"type":"reference","isActive":true,"identifier":"doc:\/\/AmiiboService\/documentation\/AmiiboService\/AmiiboService\/characters(filter:)"},{"type":"text","text":" that interacts with the respective "},{"type":"reference","isActive":true,"identifier":"https:\/\/www.amiiboapi.com\/docs\/#character"},{"type":"text","text":";"}]}]},{"content":[{"type":"paragraph","inlineContent":[{"type":"reference","isActive":true,"identifier":"doc:\/\/AmiiboService\/documentation\/AmiiboService\/AmiiboService\/gameSeries(filter:)"},{"type":"text","text":" that interacts with the respective "},{"type":"reference","isActive":true,"identifier":"https:\/\/www.amiiboapi.com\/docs\/#gameSeries"},{"type":"text","text":";"}]}]},{"content":[{"type":"paragraph","inlineContent":[{"type":"reference","isActive":true,"identifier":"doc:\/\/AmiiboService\/documentation\/AmiiboService\/AmiiboService\/lastUpdated()"},{"type":"text","text":" that interacts with the respective "},{"type":"reference","isActive":true,"identifier":"https:\/\/www.amiiboapi.com\/docs\/#lastUpdated"},{"type":"text","text":"."}]}]}]},{"type":"paragraph","inlineContent":[{"type":"text","text":"It is certainly important to highlight two points here:"}]},{"type":"orderedList","items":[{"content":[{"type":"paragraph","inlineContent":[{"type":"text","text":"these functions support the "},{"type":"codeVoice","code":"Swift concurrency"},{"type":"text","text":" (or "},{"type":"codeVoice","code":"async\/await"},{"type":"text","text":")  feature of the Swift programming language, thus they should be called within a context that already uses this feature;"}]}]},{"content":[{"type":"paragraph","inlineContent":[{"type":"text","text":"these functions would throw an error in case any issue occurred while they are executing, so it is recommendable to handle the error appropriately to guarantee the proper continuation of the application and also, a proper user experience."}]}]}]}]}],"schemaVersion":{"major":0,"minor":3,"patch":0},"sections":[],"variants":[{"paths":["\/documentation\/amiiboservice\/gettingstarted"],"traits":[{"interfaceLanguage":"swift"}]}],"identifier":{"url":"doc:\/\/AmiiboService\/documentation\/AmiiboService\/GettingStarted","interfaceLanguage":"swift"},"abstract":[{"type":"text","text":"Install the package and start using the service to retrieve any available data from the "},{"type":"reference","isActive":true,"identifier":"https:\/\/www.amiiboapi.com"},{"type":"text","text":"."}],"kind":"article","metadata":{"roleHeading":"Article","title":"Getting Started","role":"article","modules":[{"name":"AmiiboService"}]},"hierarchy":{"paths":[["doc:\/\/AmiiboService\/documentation\/AmiiboService"]]},"seeAlsoSections":[{"title":"Essentials","identifiers":["doc:\/\/AmiiboService\/documentation\/AmiiboService\/AmiiboService"],"generated":true}],"references":{"doc://AmiiboService/documentation/AmiiboService/AmiiboService/amiiboSeries(filter:)":{"role":"symbol","title":"amiiboSeries(filter:)","fragments":[{"kind":"keyword","text":"func"},{"kind":"text","text":" "},{"kind":"identifier","text":"amiiboSeries"},{"kind":"text","text":"("},{"kind":"externalParam","text":"filter"},{"kind":"text","text":": "},{"kind":"typeIdentifier","text":"AmiiboSeriesFilter","preciseIdentifier":"s:13AmiiboService0A12SeriesFiltera"},{"kind":"text","text":") "},{"kind":"keyword","text":"async"},{"kind":"text","text":" "},{"kind":"keyword","text":"throws"},{"kind":"text","text":" -> ["},{"kind":"typeIdentifier","text":"DTO","preciseIdentifier":"s:13AmiiboService3DTOO"},{"kind":"text","text":"."},{"kind":"typeIdentifier","text":"AmiiboSeries","preciseIdentifier":"s:13AmiiboService3DTOO0A6Seriesa"},{"kind":"text","text":"]"}],"abstract":[{"type":"text","text":"Retrieves a list of amiibo series from a remote location that matches a given filter criteria."}],"identifier":"doc:\/\/AmiiboService\/documentation\/AmiiboService\/AmiiboService\/amiiboSeries(filter:)","kind":"symbol","type":"topic","url":"\/documentation\/amiiboservice\/amiiboservice\/amiiboseries(filter:)"},"https://www.amiiboapi.com":{"title":"Amiibo API","titleInlineContent":[{"type":"text","text":"Amiibo API"}],"type":"link","identifier":"https:\/\/www.amiiboapi.com","url":"https:\/\/www.amiiboapi.com"},"doc://AmiiboService/documentation/AmiiboService":{"role":"collection","title":"AmiiboService","abstract":[{"type":"text","text":"Ready-to-use service that retrieves decoded entities from any of the "},{"type":"reference","isActive":true,"identifier":"https:\/\/www.amiiboapi.com"},{"type":"text","text":" available endpoints."}],"identifier":"doc:\/\/AmiiboService\/documentation\/AmiiboService","kind":"symbol","type":"topic","url":"\/documentation\/amiiboservice"},"https://www.amiiboapi.com/docs/#amiibo":{"title":"Amiibo API endpoint","titleInlineContent":[{"type":"text","text":"Amiibo API endpoint"}],"type":"link","identifier":"https:\/\/www.amiiboapi.com\/docs\/#amiibo","url":"https:\/\/www.amiiboapi.com\/docs\/#amiibo"},"doc://AmiiboService/documentation/AmiiboService/AmiiboService/amiibos(filter:)":{"role":"symbol","title":"amiibos(filter:)","fragments":[{"kind":"keyword","text":"func"},{"kind":"text","text":" "},{"kind":"identifier","text":"amiibos"},{"kind":"text","text":"("},{"kind":"externalParam","text":"filter"},{"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":"DTO","preciseIdentifier":"s:13AmiiboService3DTOO"},{"kind":"text","text":"."},{"kind":"typeIdentifier","text":"Amiibo","preciseIdentifier":"s:13AmiiboService3DTOO0A0V"},{"kind":"text","text":"]"}],"abstract":[{"type":"text","text":"Retrieves a list of amiibos from a remote location that matches a given filter criteria."}],"identifier":"doc:\/\/AmiiboService\/documentation\/AmiiboService\/AmiiboService\/amiibos(filter:)","kind":"symbol","type":"topic","url":"\/documentation\/amiiboservice\/amiiboservice\/amiibos(filter:)"},"https://www.amiiboapi.com/docs/#info":{"title":"Amiibo API documentation","titleInlineContent":[{"type":"text","text":"Amiibo API documentation"}],"type":"link","identifier":"https:\/\/www.amiiboapi.com\/docs\/#info","url":"https:\/\/www.amiiboapi.com\/docs\/#info"},"doc://AmiiboService/documentation/AmiiboService/AmiiboService":{"role":"symbol","title":"AmiiboService","fragments":[{"kind":"keyword","text":"class"},{"kind":"text","text":" "},{"kind":"identifier","text":"AmiiboService"}],"abstract":[{"type":"text","text":"This service provides the interface to make remote API calls to the "},{"type":"reference","isActive":true,"identifier":"https:\/\/www.amiiboapi.com"},{"type":"text","text":" and, subsequently, handle its responses."}],"identifier":"doc:\/\/AmiiboService\/documentation\/AmiiboService\/AmiiboService","kind":"symbol","type":"topic","navigatorTitle":[{"kind":"identifier","text":"AmiiboService"}],"url":"\/documentation\/amiiboservice\/amiiboservice"},"https://www.amiiboapi.com/docs/#type":{"title":"Amiibo API endpoint","titleInlineContent":[{"type":"text","text":"Amiibo API endpoint"}],"type":"link","identifier":"https:\/\/www.amiiboapi.com\/docs\/#type","url":"https:\/\/www.amiiboapi.com\/docs\/#type"},"https://www.amiiboapi.com/docs/#series":{"title":"Amiibo API endpoint","titleInlineContent":[{"type":"text","text":"Amiibo API endpoint"}],"type":"link","identifier":"https:\/\/www.amiiboapi.com\/docs\/#series","url":"https:\/\/www.amiiboapi.com\/docs\/#series"},"doc://AmiiboService/documentation/AmiiboService/AmiiboService/lastUpdated()":{"role":"symbol","title":"lastUpdated()","fragments":[{"kind":"keyword","text":"func"},{"kind":"text","text":" "},{"kind":"identifier","text":"lastUpdated"},{"kind":"text","text":"() "},{"kind":"keyword","text":"async"},{"kind":"text","text":" "},{"kind":"keyword","text":"throws"},{"kind":"text","text":" -> "},{"kind":"typeIdentifier","text":"DTO","preciseIdentifier":"s:13AmiiboService3DTOO"},{"kind":"text","text":"."},{"kind":"typeIdentifier","text":"LastUpdated","preciseIdentifier":"s:13AmiiboService3DTOO11LastUpdatedV"}],"abstract":[{"type":"text","text":"Retrieves the date in which the remote API was last updated."}],"identifier":"doc:\/\/AmiiboService\/documentation\/AmiiboService\/AmiiboService\/lastUpdated()","kind":"symbol","type":"topic","url":"\/documentation\/amiiboservice\/amiiboservice\/lastupdated()"},"doc://AmiiboService/documentation/AmiiboService/AmiiboService/characters(filter:)":{"role":"symbol","title":"characters(filter:)","fragments":[{"kind":"keyword","text":"func"},{"kind":"text","text":" "},{"kind":"identifier","text":"characters"},{"kind":"text","text":"("},{"kind":"externalParam","text":"filter"},{"kind":"text","text":": "},{"kind":"typeIdentifier","text":"CharacterFilter","preciseIdentifier":"s:13AmiiboService15CharacterFiltera"},{"kind":"text","text":") "},{"kind":"keyword","text":"async"},{"kind":"text","text":" "},{"kind":"keyword","text":"throws"},{"kind":"text","text":" -> ["},{"kind":"typeIdentifier","text":"DTO","preciseIdentifier":"s:13AmiiboService3DTOO"},{"kind":"text","text":"."},{"kind":"typeIdentifier","text":"Character","preciseIdentifier":"s:13AmiiboService3DTOO9Charactera"},{"kind":"text","text":"]"}],"abstract":[{"type":"text","text":"Retrieves a list of characters from a remote location that matches a given filter criteria."}],"identifier":"doc:\/\/AmiiboService\/documentation\/AmiiboService\/AmiiboService\/characters(filter:)","kind":"symbol","type":"topic","url":"\/documentation\/amiiboservice\/amiiboservice\/characters(filter:)"},"https://www.amiiboapi.com/docs/#gameSeries":{"title":"Amiibo API endpoint","titleInlineContent":[{"type":"text","text":"Amiibo API endpoint"}],"type":"link","identifier":"https:\/\/www.amiiboapi.com\/docs\/#gameSeries","url":"https:\/\/www.amiiboapi.com\/docs\/#gameSeries"},"https://www.amiiboapi.com/docs/#character":{"title":"Amiibo API endpoint","titleInlineContent":[{"type":"text","text":"Amiibo API endpoint"}],"type":"link","identifier":"https:\/\/www.amiiboapi.com\/docs\/#character","url":"https:\/\/www.amiiboapi.com\/docs\/#character"},"doc://AmiiboService/documentation/AmiiboService/AmiiboService/gameSeries(filter:)":{"role":"symbol","title":"gameSeries(filter:)","fragments":[{"kind":"keyword","text":"func"},{"kind":"text","text":" "},{"kind":"identifier","text":"gameSeries"},{"kind":"text","text":"("},{"kind":"externalParam","text":"filter"},{"kind":"text","text":": "},{"kind":"typeIdentifier","text":"GameSeriesFilter","preciseIdentifier":"s:13AmiiboService16GameSeriesFiltera"},{"kind":"text","text":") "},{"kind":"keyword","text":"async"},{"kind":"text","text":" "},{"kind":"keyword","text":"throws"},{"kind":"text","text":" -> ["},{"kind":"typeIdentifier","text":"DTO","preciseIdentifier":"s:13AmiiboService3DTOO"},{"kind":"text","text":"."},{"kind":"typeIdentifier","text":"GameSeries","preciseIdentifier":"s:13AmiiboService3DTOO10GameSeriesa"},{"kind":"text","text":"]"}],"abstract":[{"type":"text","text":"Retrieves a list of game series from a remote location that matches a given filter criteria."}],"identifier":"doc:\/\/AmiiboService\/documentation\/AmiiboService\/AmiiboService\/gameSeries(filter:)","kind":"symbol","type":"topic","url":"\/documentation\/amiiboservice\/amiiboservice\/gameseries(filter:)"},"doc://AmiiboService/documentation/AmiiboService/AmiiboService/amiiboTypes(filter:)":{"role":"symbol","title":"amiiboTypes(filter:)","fragments":[{"kind":"keyword","text":"func"},{"kind":"text","text":" "},{"kind":"identifier","text":"amiiboTypes"},{"kind":"text","text":"("},{"kind":"externalParam","text":"filter"},{"kind":"text","text":": "},{"kind":"typeIdentifier","text":"AmiiboTypeFilter","preciseIdentifier":"s:13AmiiboService0A10TypeFiltera"},{"kind":"text","text":") "},{"kind":"keyword","text":"async"},{"kind":"text","text":" "},{"kind":"keyword","text":"throws"},{"kind":"text","text":" -> ["},{"kind":"typeIdentifier","text":"DTO","preciseIdentifier":"s:13AmiiboService3DTOO"},{"kind":"text","text":"."},{"kind":"typeIdentifier","text":"AmiiboType","preciseIdentifier":"s:13AmiiboService3DTOO0A4Typea"},{"kind":"text","text":"]"}],"abstract":[{"type":"text","text":"Retrieves a list of amiibo types from a remote location that matches a given filter criteria."}],"identifier":"doc:\/\/AmiiboService\/documentation\/AmiiboService\/AmiiboService\/amiiboTypes(filter:)","kind":"symbol","type":"topic","url":"\/documentation\/amiiboservice\/amiiboservice\/amiibotypes(filter:)"},"https://www.amiiboapi.com/docs/#lastUpdated":{"title":"Amiibo API endpoint","titleInlineContent":[{"type":"text","text":"Amiibo API endpoint"}],"type":"link","identifier":"https:\/\/www.amiiboapi.com\/docs\/#lastUpdated","url":"https:\/\/www.amiiboapi.com\/docs\/#lastUpdated"}}}