rock-n-code/amiibo-service
1
0
Fork 0
Code Issues Pull Requests Actions Releases 15 Activity
Files
main
amiibo-service/Sources/AmiiboService/openapi.yaml
T
javier 61695af072 Improved the summaries and descriptions through the OpenAPI specification document in the library target. (#24) 
Reviewed-on: #24
Co-authored-by: Javier Cicchelli <javier@rock-n-code.com>
Co-committed-by: Javier Cicchelli <javier@rock-n-code.com>
2026-03-23 00:20:33 +00:00

609 lines
22 KiB
YAML
Raw Permalink 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, optionally filtered by various criteria such as name, type, series, or game.
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 zero, one or more amiibos matching the filter criteria.
content:
application/json:
schema:
$ref: '#/components/schemas/AmiiboWrapper'
'400':
$ref: '#/components/responses/BadRequest'
'404':
$ref: '#/components/responses/NotFound'
'500':
description: The service is currently unavailable.
/amiiboseries:
get:
tags:
- Amiibo
summary: Get the amiibo series.
description: |
Get a list of all the amiibo series available in the database, optionally filtered by key or name.
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 to include in the response.
responses:
'200':
description: Successful response returning an object that contains one or more amiibo series matching the filter criteria.
content:
application/json:
schema:
$ref: '#/components/schemas/AmiiboSeriesWrapper'
'400':
$ref: '#/components/responses/BadRequest'
'404':
$ref: '#/components/responses/NotFound'
'500':
description: The service is currently unavailable.
/character:
get:
tags:
- Game
summary: Get the game characters.
description: |
Get a list of all the game characters available in the database, optionally filtered by key or name.
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 to include in the response.
- $ref: '#/components/parameters/Name'
description: A name of a game character to include in the response.
responses:
'200':
description: Successful response returning an object that contains one or more game characters matching the filter criteria.
content:
application/json:
schema:
$ref: '#/components/schemas/GameCharacterWrapper'
'400':
$ref: '#/components/responses/BadRequest'
'404':
$ref: '#/components/responses/NotFound'
'500':
description: The service is currently unavailable.
/gameseries:
get:
tags:
- Game
summary: Get the game series.
description: |
Get a list of all the game series available in the database, optionally filtered by key or name.
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 matching the filter criteria.
content:
application/json:
schema:
$ref: '#/components/schemas/GameSeriesWrapper'
'400':
$ref: '#/components/responses/BadRequest'
'404':
$ref: '#/components/responses/NotFound'
'500':
description: The service is currently unavailable.
/type:
get:
tags:
- Amiibo
summary: Get the amiibo types.
description: |
Get a list of all the amiibo types available in the database, optionally filtered by key or name.
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 matching the filter criteria.
content:
application/json:
schema:
$ref: '#/components/schemas/AmiiboTypeWrapper'
'400':
$ref: '#/components/responses/BadRequest'
'404':
$ref: '#/components/responses/NotFound'
'500':
description: The service is currently unavailable.
/lastupdated:
get:
tags:
- Service
summary: Get the date when data was last updated.
description: |
Get an ISO-formatted date and 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 the date and time when the database was last updated.
content:
application/json:
schema:
$ref: '#/components/schemas/LastUpdated'
'500':
description: The service is currently unavailable.
components:
parameters:
AmiiboSeries:
description: A hexadecimal key or name of an amiibo series to include in the response.
name: amiiboSeries
in: query
required: false
schema:
type: string
AmiiboType:
description: A hexadecimal key or name of an amiibo type to include in the response.
name: type
in: query
required: false
schema:
type: string
GameCharacter:
description: A hexadecimal key or name of a game character to include in the response.
name: character
in: query
required: false
schema:
type: string
GameSeries:
description: A hexadecimal key or name of a game series to include in the response.
name: gameseries
in: query
required: false
schema:
type: string
Identifier:
description: The full 16-character hexadecimal identifier of an amiibo to include in the response.
name: id
in: query
required: false
schema:
type: string
maxLength: 18
IdentifierHead:
description: The first 8 hexadecimal characters of an amiibo identifier to include in the response.
name: head
in: query
required: false
schema:
type: string
maxLength: 10
IdentifierTail:
description: The last 8 hexadecimal characters of an amiibo identifier to include in the response.
name: tail
in: query
required: false
schema:
type: string
maxLength: 10
Key:
description: A hexadecimal key to filter the results by.
name: key
in: query
required: false
schema:
type: string
Name:
description: A name to filter the results by.
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: The request was malformed or contained invalid parameters.
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
NotFound:
description: No results were found matching the given filter criteria.
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
schemas:
# Core Entities
Amiibo:
description: A type that represents an amiibo figurine, card, or other collectible.
type: object
properties:
amiiboSeries:
description: The name of the amiibo series this amiibo belongs to.
type: string
character:
description: |
The name of the game character associated with this amiibo.
Multiple characters can have different amiibo designs.
type: string
gameSeries:
description: The name of the game series associated with this amiibo.
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: A URL pointing to an image of this amiibo.
type: string
format: uri
name:
description: The name of this amiibo.
type: string
release:
description: The regional release dates of this amiibo, if known.
$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: The type of this amiibo (e.g., Figure, Card, Yarn, Band).
type: string
required:
- amiiboSeries
- character
- gameSeries
- head
- image
- name
- release
- tail
- type
AmiiboGame:
description: A type that represents a game in which an amiibo can be used.
type: object
properties:
amiiboUsage:
description: A list of available usages an amiibo has in a game, if any.
type: array
items:
$ref: '#/components/schemas/AmiiboUsage'
gameID:
description: A list of identifiers for the game.
type: array
items:
type: string
gameName:
description: The name of the game.
type: string
required:
- gameID
- gameName
AmiiboRelease:
description: A type that contains the regional release dates of an amiibo.
type: object
properties:
au:
description: The release date in Australia, if known.
type: string
format: date-time
eu:
description: The release date in Europe, if known.
type: string
format: date-time
jp:
description: The release date in Japan, if known.
type: string
format: date-time
na:
description: The release date in North America, if known.
type: string
format: date-time
AmiiboSeries:
description: A type that represents an amiibo series.
allOf:
- $ref: '#/components/schemas/Tuple'
- type: object
properties:
key:
description: The hexadecimal key that uniquely identifies this amiibo series.
name:
description: The name of this amiibo series.
AmiiboType:
description: A type that represents an amiibo type (e.g., Figure, Card, Yarn, Band).
allOf:
- $ref: '#/components/schemas/Tuple'
- type: object
properties:
key:
description: The hexadecimal key that uniquely identifies this amiibo type.
name:
description: The name of this amiibo type.
AmiiboUsage:
description: A type that represents how an amiibo is used within a game.
type: object
properties:
Usage:
description: A description of how the amiibo is used within the game.
type: string
write:
description: A flag that indicates whether the amiibo can save game data.
type: boolean
required:
- Usage
- write
GameCharacter:
description: A type that represents a game character.
allOf:
- $ref: '#/components/schemas/Tuple'
- type: object
properties:
key:
description: The hexadecimal key that uniquely identifies this game character.
name:
description: The name of this game character.
GameSeries:
description: A type that represents a game series.
allOf:
- $ref: '#/components/schemas/Tuple'
- type: object
properties:
key:
description: The hexadecimal key that uniquely identifies this game series.
name:
description: The name of this game series.
LastUpdated:
description: A type that contains the date and time when the service data 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 base type composed of a `key` and `name` pair.
This type is the base schema for the `AmiiboSeries`, `AmiiboType`, `GameCharacter`, and `GameSeries` types.
type: object
properties:
key:
description: A hexadecimal key that uniquely identifies this resource.
type: string
pattern: "^0x[0-9a-fA-F]+$"
minLength: 3
name:
description: A display name for this resource.
type: string
required:
- key
- name
# Wrapper Entities
AmiiboWrapper:
description: A response wrapper that contains zero, one, or more amiibos.
type: object
properties:
amiibo:
description: A container that holds 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 response wrapper that contains one or more amiibo series.
type: object
properties:
amiibo:
description: A container that holds 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 response wrapper that contains one or more amiibo types.
type: object
properties:
amiibo:
description: A container that holds 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 response wrapper that contains one or more game characters.
type: object
properties:
amiibo:
description: A container that holds 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 response wrapper that contains one or more game series.
type: object
properties:
amiibo:
description: A container that holds 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 response from the service.
type: object
properties:
code:
description: The HTTP status code of the error.
type: integer
error:
description: A human-readable message describing the error.
type: string
required:
- code
- error
Reference in New Issue View Git Blame Copy Permalink