453 lines
15 KiB
YAML
453 lines
15 KiB
YAML
## ===----------------------------------------------------------------------===
|
|
##
|
|
## This source file is part of the Amiibo Service open source project
|
|
##
|
|
## Copyright (c) 2025 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
|
|
|
|
_AmiiboAPI_ 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.com/docs/#termscondition
|
|
contact:
|
|
name: FAQ
|
|
url: https://www.amiiboapi.com/faq/
|
|
license:
|
|
name: MIT license
|
|
identifier: MIT
|
|
servers:
|
|
- url: https://www.amiiboapi.com/api
|
|
description: Live service
|
|
tags:
|
|
- name: Amiibo
|
|
description: Amiibo-related endpoints.
|
|
- name: Game
|
|
description: Game-related endpoints.
|
|
- name: Service
|
|
description: Service-related endpoints.
|
|
externalDocs:
|
|
url: https://www.amiiboapi.com/docs
|
|
description: Amiibo API documentation
|
|
paths:
|
|
/amiibo:
|
|
get:
|
|
summary: Get a list of Amiibo items.
|
|
description: Get a list of all the Amiibo items available in the database.
|
|
operationId: getAmiibos
|
|
tags:
|
|
- Amiibo
|
|
responses:
|
|
'200':
|
|
description: Response that retuns a decodable JSON object wrapping a list of Amiibo items.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/AmiiboWrapper'
|
|
'400':
|
|
description: An amiibo bad request.
|
|
'404':
|
|
description: An amiibo not found.
|
|
'500':
|
|
description: Service is not available.
|
|
parameters:
|
|
- name: amiiboSeries
|
|
in: query
|
|
description: An identifier or name of an Amiibo to filter the response.
|
|
required: false
|
|
schema:
|
|
type: string
|
|
style: form
|
|
- name: character
|
|
in: query
|
|
description: An identifier or name of a game character to filter the response.
|
|
required: false
|
|
schema:
|
|
type: string
|
|
style: form
|
|
- name: gameseries
|
|
in: query
|
|
description: An identifier or name of a game series to filter the response.
|
|
required: false
|
|
schema:
|
|
type: string
|
|
style: form
|
|
- name: head
|
|
in: query
|
|
description: A last part of an identifier to filter the response.
|
|
required: false
|
|
schema:
|
|
type: string
|
|
style: form
|
|
- name: id
|
|
in: query
|
|
description: An identifier of an Amiibo to filter the response.
|
|
required: false
|
|
schema:
|
|
type: string
|
|
style: form
|
|
- name: name
|
|
in: query
|
|
description: A name of an Amiibo to filter the response.
|
|
required: false
|
|
schema:
|
|
type: string
|
|
style: form
|
|
- name: showgames
|
|
in: query
|
|
description: A flag that indicates whether to include information about related games.
|
|
required: false
|
|
schema:
|
|
type: boolean
|
|
style: form
|
|
- name: showusage
|
|
in: query
|
|
description: A flag that indicates whether to include information about Amiibo usage in related games.
|
|
required: false
|
|
schema:
|
|
type: boolean
|
|
style: form
|
|
- name: tail
|
|
in: query
|
|
description: A first part of an identifier to filter the response.
|
|
required: false
|
|
schema:
|
|
type: string
|
|
style: form
|
|
- name: type
|
|
in: query
|
|
description: An identifier or a name of an Amiibo type to filter the response.
|
|
required: false
|
|
schema:
|
|
type: string
|
|
style: form
|
|
/amiiboseries:
|
|
get:
|
|
description: Get a list of all the Amiibo series available in the database.
|
|
operationId: getAmiiboSeries
|
|
tags:
|
|
- Amiibo
|
|
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':
|
|
$ref: '#/components/responses/SuccessTuple'
|
|
'400':
|
|
description: An amiibo series bad request.
|
|
'404':
|
|
description: An amiibo series not found.
|
|
'500':
|
|
description: Service is not available.
|
|
/character:
|
|
get:
|
|
description: Get a list of all the game characters available in the database.
|
|
operationId: getGameCharacters
|
|
tags:
|
|
- Game
|
|
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':
|
|
$ref: '#/components/responses/SuccessTuple'
|
|
'400':
|
|
description: A game character bad request.
|
|
'404':
|
|
description: A game character not found.
|
|
'500':
|
|
description: Service is not available.
|
|
/gameseries:
|
|
get:
|
|
description: Gets a list of all the game series available in the database.
|
|
operationId: getGameSeries
|
|
tags:
|
|
- Game
|
|
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':
|
|
$ref: '#/components/responses/SuccessTuple'
|
|
'400':
|
|
description: A game series bad request.
|
|
'404':
|
|
description: A game series not found.
|
|
'500':
|
|
description: Service is not available.
|
|
/type:
|
|
get:
|
|
description: Gets a list of all the Amiibo types available in the database.
|
|
operationId: getAmiiboTypes
|
|
tags:
|
|
- Amiibo
|
|
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':
|
|
$ref: '#/components/responses/SuccessTuple'
|
|
'400':
|
|
description: An amiibo type bad request.
|
|
'404':
|
|
description: An amiibo type not found.
|
|
'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.com/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:
|
|
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
|
|
responses:
|
|
SuccessTuple:
|
|
description: Response that returns a JSON object containing requested `Tuple` data from a resource.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/TupleWrapper'
|
|
schemas:
|
|
# Core Entities
|
|
Amiibo:
|
|
description: A type that contains all the information about an Amiibo.
|
|
type: object
|
|
properties:
|
|
amiiboSeries:
|
|
description: A name of the series the 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 the game series the 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'
|
|
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
|
|
image:
|
|
description: An image URL related to an Amiibo.
|
|
type: string
|
|
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
|
|
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
|
|
AmiiboList:
|
|
description: A type that contains a list of `Amiibo` instances.
|
|
type: array
|
|
items:
|
|
description: A list if `Amiibo` instance.
|
|
$ref: '#/components/schemas/Amiibo'
|
|
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
|
|
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
|
|
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
|
|
# Wrapper Entities
|
|
AmiiboWrapper:
|
|
description: A type that contains either one or multiple `Amiibo` instances.
|
|
type: object
|
|
properties:
|
|
amiibo:
|
|
description: A property that contains one or multiple `Amiibo` instances.
|
|
oneOf:
|
|
- $ref: '#/components/schemas/Amiibo'
|
|
- $ref: '#/components/schemas/AmiiboList'
|
|
required:
|
|
- amiibo
|
|
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
|
|
name:
|
|
description: A name assigned to a tuple.
|
|
type: string
|
|
required:
|
|
- key
|
|
- name
|
|
TupleList:
|
|
description: A type that represents a list of key/value tuples.
|
|
type: array
|
|
items:
|
|
description: A property that can contains multiple `Tuple` instances.
|
|
$ref: '#/components/schemas/Tuple'
|
|
TupleWrapper:
|
|
description: A type that contains either one or multiple `Tuple` instances.
|
|
type: object
|
|
properties:
|
|
amiibo:
|
|
description: A property that contains one or multiple `Tuple` instances.
|
|
oneOf:
|
|
- $ref: '#/components/schemas/Tuple'
|
|
- $ref: '#/components/schemas/TupleList'
|
|
required:
|
|
- amiibo
|