rock-n-code/amiibo-service
1
0
Fork 0
Code Issues Pull Requests Actions Releases 15 Activity
Files
2b01ec14bfdac12543f2334a8b8bbd6c968acebf
amiibo-service/Sources/AmiiboService/openapi.yaml
T
javier 2b01ec14bf Overall improvements and data update (#22) 
This PR contains the work done to update the live tests to the latest data plus lots of QoL improvements to the library, including:

* added test cases to test the ``AmiiboService` locally;
* conformed the models to the `Hashable` protocol;
* documented the use of caching with the `AmiiboService` service;
* updated the reference to the new AmiiboAPI url;
* updated the year on the copyrights and header files;
* updated the overall documentation of the source code and the package.

Reviewed-on: #22
Co-authored-by: Javier Cicchelli <javier@rock-n-code.com>
Co-committed-by: Javier Cicchelli <javier@rock-n-code.com>
2026-03-22 23:39:48 +00:00

609 lines
21 KiB
YAML
Raw Blame History

## ===----------------------------------------------------------------------===
##
## This source file is part of the Amiibo Service open source project
##
## Copyright (c) 2026 Röck+Cöde VoF. and the Amiibo Service project authors
## Licensed under Apache license v2.0
##
## See LICENSE for license information
## See CONTRIBUTORS for the list of Amiibo Service project authors
##
## SPDX-License-Identifier: Apache-2.0
##
## ===----------------------------------------------------------------------===
openapi: '3.1.1'
info:
title: Amiibo API
summary: A RESTFul API for Amiibo.
description: |
# Information
The [AmiiboAPI](https://www.amiiboapi.org) service is primarily used for educational purposes.
This is a **reading-only API**. Only HTTP GET method is allowed by this API.
**No authentication** is required to use this API. All resources are allowed to access.
If you are going to be calling this API regularly. We recommend that you use **caching** on your system.
# Terms & Conditions
By using our API, you hereby accepted the following terms and conditions:
* *This API has no affiliation with Nintendo or any other companies that own the rights to it.*
* *Other reports collected by the respective companies that own the rights are not our responsibility.*
* *User agrees that the use of this API is entirely at user's own risks.*
* *You will require your end users to comply with (and not knowingly enable them to violate) applicable law, regulation, and the Terms.*
* *You will comply with all applicable law, regulation, and third party rights (including without limitation laws regarding the import or export of data or software, privacy, and local laws). You will not use the APIs to encourage or promote illegal activity or violation of third party rights.*
* *These Terms and Conditions are subject to change without notice, from time to time in our sole discretion.*
version: v1.0.0
termsOfService: https://www.amiiboapi.org/docs/#termscondition
contact:
name: FAQ
url: https://www.amiiboapi.org/faq/
license:
name: MIT license
identifier: MIT
externalDocs:
url: https://www.amiiboapi.org/docs
description: Amiibo API documentation
servers:
- url: https://www.amiiboapi.org/api
description: Live service
tags:
- name: Amiibo
description: Amiibo-related endpoints.
- name: Game
description: Game-related endpoints.
- name: Service
description: Service-related endpoints.
paths:
/amiibo:
get:
summary: Get a list of amiibos.
description: |
Get a list of all the Amiibo items available in the database.
Please refer to [the documentation of the endpoint](https://www.amiiboapi.org/docs/#amiibo) for further information.
operationId: getAmiibos
tags:
- Amiibo
parameters:
- $ref: '#/components/parameters/Identifier'
- $ref: '#/components/parameters/IdentifierHead'
- $ref: '#/components/parameters/IdentifierTail'
- $ref: '#/components/parameters/Name'
description: A name of an amiibo to include in the response.
- $ref: '#/components/parameters/AmiiboType'
- $ref: '#/components/parameters/AmiiboSeries'
- $ref: '#/components/parameters/GameCharacter'
- $ref: '#/components/parameters/GameSeries'
- $ref: '#/components/parameters/ShowGames'
- $ref: '#/components/parameters/ShowUsage'
responses:
'200':
description: Successful response returning an object that contains none, one or more amiibos.
content:
application/json:
schema:
$ref: '#/components/schemas/AmiiboWrapper'
'400':
$ref: '#/components/responses/BadRequest'
'404':
$ref: '#/components/responses/NotFound'
'500':
description: Service is not available.
/amiiboseries:
get:
tags:
- Amiibo
summary: Get the amiibo series.
description: |
Get a list of all the Amiibo series available in the database.
Please refer to [the documentation of the endpoint](https://www.amiiboapi.org/docs/#series) for further information.
operationId: getAmiiboSeries
parameters:
- $ref: '#/components/parameters/Key'
description: A key of an amiibo series to include in the response.
- $ref: '#/components/parameters/Name'
description: A name of an amiibo series key to include in the response.
responses:
'200':
description: Successful response returning an object that contains one or more amiibo series.
content:
application/json:
schema:
$ref: '#/components/schemas/AmiiboSeriesWrapper'
'400':
$ref: '#/components/responses/BadRequest'
'404':
$ref: '#/components/responses/NotFound'
'500':
description: Service is not available.
/character:
get:
tags:
- Game
summary: Get the game characters.
description: |
Get a list of all the game characters available in the database.
Please refer to [the documentation of the endpoint](https://www.amiiboapi.org/docs/#character) for further information.
operationId: getGameCharacters
parameters:
- $ref: '#/components/parameters/Key'
description: A key of a game character key to include in the response.
- $ref: '#/components/parameters/Name'
description: A name of a game character key to include in the response.
responses:
'200':
description: Successful response returning an object that contains one or more game characters.
content:
application/json:
schema:
$ref: '#/components/schemas/GameCharacterWrapper'
'400':
$ref: '#/components/responses/BadRequest'
'404':
$ref: '#/components/responses/NotFound'
'500':
description: Service is not available.
/gameseries:
get:
tags:
- Game
summary: Get the game series.
description: |
Gets a list of all the Game series available in the database.
Please refer to [the documentation of the endpoint](https://www.amiiboapi.org/docs/#gameSeries) for further information.
operationId: getGameSeries
parameters:
- $ref: '#/components/parameters/Key'
description: A key of a game series to include in the response.
- $ref: '#/components/parameters/Name'
description: A name of a game series to include in the response.
responses:
'200':
description: Successful response returning an object that contains one or more game series.
content:
application/json:
schema:
$ref: '#/components/schemas/GameSeriesWrapper'
'400':
$ref: '#/components/responses/BadRequest'
'404':
$ref: '#/components/responses/NotFound'
'500':
description: Service is not available.
/type:
get:
tags:
- Amiibo
summary: Get the amiibo types.
description: |
Gets a list of all the amiibo types available in the database.
Please refer to [the documentation of the endpoint](https://www.amiiboapi.org/docs/#type) for further information.
operationId: getAmiiboTypes
parameters:
- $ref: '#/components/parameters/Key'
description: A key of an amiibo type to include in the response.
- $ref: '#/components/parameters/Name'
description: A name of an amiibo type to include in the response.
responses:
'200':
description: Successful response returning an object that contains one or more amiibo types.
content:
application/json:
schema:
$ref: '#/components/schemas/AmiiboTypeWrapper'
'400':
$ref: '#/components/responses/BadRequest'
'404':
$ref: '#/components/responses/NotFound'
'500':
description: Service is not available.
/lastupdated:
get:
tags:
- Service
summary: Get the date of last updated.
description: |
Gets an ISO-formatted date+time when the Amiibo data was last updated.
Please refer to [the documentation of the endpoint](https://www.amiiboapi.org/docs/#lastUpdated) for further information.
operationId: getLastUpdated
responses:
'200':
description: Successful response returning an object that contains a date and time when the database was last updated.
content:
application/json:
schema:
$ref: '#/components/schemas/LastUpdated'
'500':
description: Service is not available.
components:
parameters:
AmiiboSeries:
description: An identifier or name of an amiibo series to include in the response
name: amiiboSeries
in: query
required: false
schema:
type: string
AmiiboType:
description: An identifier or a name of an amiibo type to inclulde in the response.
name: type
in: query
required: false
schema:
type: string
GameCharacter:
description: An identifier or name of a game character to include in the response.
name: character
in: query
required: false
schema:
type: string
GameSeries:
description: An identifier or name of a game series to include in the response.
name: gameseries
in: query
required: false
schema:
type: string
Identifier:
description: An identifier of an amiibo to include in the response.
name: id
in: query
required: false
schema:
type: string
maxLength: 18
IdentifierHead:
description: A first part for an identifier of an amiibo to include the response.
name: head
in: query
required: false
schema:
type: string
maxLength: 10
IdentifierTail:
description: A last part for an identifier of an amiibo to include the response.
name: tail
in: query
required: false
schema:
type: string
maxLength: 10
Key:
description: A key of a type to include in the response.
name: key
in: query
required: false
schema:
type: string
Name:
description: A name of a type to include in the response.
name: name
in: query
required: false
schema:
type: string
ShowGames:
description: A flag that indicates whether to include information about related games.
name: showgames
in: query
required: false
schema:
type: boolean
ShowUsage:
description: A flag that indicates whether to include information about amiibo usages in related games.
name: showusage
in: query
required: false
schema:
type: boolean
responses:
BadRequest:
description: One or more incorrect parameters have been sent.
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
NotFound:
description: No resource has been found.
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
schemas:
# Core Entities
Amiibo:
description: A type that represents an amiibo.
type: object
properties:
amiiboSeries:
description: A name of a series an amiibo belongs to.
type: string
character:
description: |
A name of a character of an amiibo.
Multiple character have different amiibo design.
type: string
gameSeries:
description: A name of a game series an amiibo belongs to.
type: string
games3DS:
description: A list of 3DS games an amiibo could be used in, if any.
type: array
items:
$ref: '#/components/schemas/AmiiboGame'
gamesSwitch:
description: A list of Switch games an amiibo could be used in, if any.
type: array
items:
$ref: '#/components/schemas/AmiiboGame'
gamesSwitch2:
description: A list of Switch 2 games an amiibo could be used in, if any.
type: array
items:
$ref: '#/components/schemas/AmiiboGame'
gamesWiiU:
description: A list of Wii U games an amiibo could be used in, if any.
type: array
items:
$ref: '#/components/schemas/AmiiboGame'
head:
description: |
The first 8 characters of the hexadecimal value that identifies an amiibo.
The positions 0 to 7 of the hexadecimal string.
type: string
pattern: "^[0-9a-fA-F]+$"
minLength: 8
maxLength: 8
image:
description: An image URL related to an amiibo.
type: string
format: uri
name:
description: A name of an Amiibo.
type: string
release:
description: A type that contains the release dates of an amiibo, if any.
$ref: '#/components/schemas/AmiiboRelease'
tail:
description: |
The last 8 characters of the hexadecimal value that identifies an amiibo.
The positions 8 to 15 of the hexadecimal string.
type: string
pattern: "^[0-9a-fA-F]+$"
minLength: 8
maxLength: 8
type:
description: A name for the type an amiibo belongs to.
type: string
required:
- amiiboSeries
- character
- gameSeries
- head
- image
- name
- release
- tail
- type
AmiiboGame:
description: A type that represents a game in which an amiibo is related to.
type: object
properties:
amiiboUsage:
description: A list of available usages an amiibo have in a game, if any.
type: array
items:
$ref: '#/components/schemas/AmiiboUsage'
gameID:
description: A list of identifiers of a game an amiibo is related to.
type: array
items:
type: string
gameName:
description: A name of a game an amiibo is related to.
type: string
required:
- gameID
- gameName
AmiiboRelease:
description: A type that contains the release dates of an amiibo throughout the world.
type: object
properties:
au:
description: A release date for Australia, if any.
type: string
format: date-time
eu:
description: A release date for Europe, if any.
type: string
format: date-time
jp:
description: A release date for Japan, if any.
type: string
format: date-time
na:
description: A release date for North America, if any.
type: string
format: date-time
AmiiboSeries:
description: A type that represents an amiibo series.
allOf:
- $ref: '#/components/schemas/Tuple'
- type: object
properties:
key:
description: A key of an amiibo series.
name:
description: A name of an amiibo series.
AmiiboType:
description: A type that represents an amiibo type.
allOf:
- $ref: '#/components/schemas/Tuple'
- type: object
properties:
key:
description: A key of an amiibo type.
name:
description: A name of an amiibo type.
AmiiboUsage:
description: A type that represents a use of an amiibo in a game.
type: object
properties:
Usage:
description: An explanation of the usage of an amiibo in a game.
type: string
write:
description: A flag that indicates whether the data in an amiibo is writable or not.
type: boolean
required:
- Usage
- write
GameCharacter:
description: A type that represents a game character.
allOf:
- $ref: '#/components/schemas/Tuple'
- type: object
properties:
key:
description: A key of a game character.
name:
description: A name of a game character.
GameSeries:
description: A type that represents a game series.
allOf:
- $ref: '#/components/schemas/Tuple'
- type: object
properties:
key:
description: A key of a game series.
name:
description: A name of a game series.
LastUpdated:
description: A type that informs when the data in the service was last updated.
type: object
properties:
lastUpdated:
description: The date and time when the data in the database was last updated.
type: string
format: date-time
required:
- lastUpdated
Tuple:
description: |
A type that is conformed only by the `key` and `name` properties.
This type represents either `AmiiboSeries`, `AmiiboType`, `GameCharacter`, and `GameSeries` types.
type: object
properties:
key:
description: A key assigned to a tuple.
type: string
pattern: "^0x[0-9a-fA-F]+$"
minLength: 3
name:
description: A name assigned to a tuple.
type: string
required:
- key
- name
# Wrapper Entities
AmiiboWrapper:
description: A type that wraps either none, one or a list of amiibos.
type: object
properties:
amiibo:
description: A container that have zero, one or more amiibos.
oneOf:
- $ref: '#/components/schemas/Amiibo'
description: A certain amiibo.
- type: array
description: A list that contains amiibos.
items:
$ref: '#/components/schemas/Amiibo'
AmiiboSeriesWrapper:
description: A type that wraps either one or a list of amiibo series.
type: object
properties:
amiibo:
description: A container that have one or more amiibo series.
oneOf:
- $ref: '#/components/schemas/AmiiboSeries'
description: A certain amiibo series.
- type: array
description: A list that contains amiibo series.
items:
$ref: '#/components/schemas/AmiiboSeries'
required:
- amiibo
AmiiboTypeWrapper:
description: A type that wraps either one or a list of amiibo types.
type: object
properties:
amiibo:
description: A container that have one or more amiibo types.
oneOf:
- $ref: '#/components/schemas/AmiiboType'
description: A certain amiibo type.
- type: array
description: A list that contains amiibo types.
items:
$ref: '#/components/schemas/AmiiboType'
required:
- amiibo
GameCharacterWrapper:
description: A type that wraps either one or a list of game characters.
type: object
properties:
amiibo:
description: A container that have one or more game characters.
oneOf:
- $ref: '#/components/schemas/GameCharacter'
description: A certain game character.
- type: array
description: A list that contains game characters.
items:
$ref: '#/components/schemas/GameCharacter'
required:
- amiibo
GameSeriesWrapper:
description: A type that wraps either one or a list of game series.
type: object
properties:
amiibo:
description: A container that have one or more game series.
oneOf:
- $ref: '#/components/schemas/GameSeries'
description: A certain game series.
- type: array
description: A list that contains game series.
items:
$ref: '#/components/schemas/GameSeries'
required:
- amiibo
# Error Entities
ServiceError:
description: A type that represents an error provided by the service.
type: object
properties:
code:
description: A number of an error code.
type: integer
error:
description: An explanation of an error.
type: string
required:
- code
- error
Reference in New Issue View Git Blame Copy Permalink