# ===----------------------------------------------------------------------===
# 
# This source file is part of the AmiiboService open source project
# 
# Copyright (c) 2024-2025 Röck+Cöde VoF. and the AmiiboAPI project authors
# Licensed under the EUPL 1.2 or later.
# 
# See LICENSE for license information
# See CONTRIBUTORS for the list of AmiiboAPI project authors
# 
# ===----------------------------------------------------------------------===

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
      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.
    parameters:
      - name: key
        in: query
        description: The Amiibo series key to filter the response.
        required: false
        schema:
          type: string
        style: form
      - name: name
        in: query
        description: The Amiibo series name to filter the response.
        required: false
        schema:
          type: string
        style: form
  /character:
    get:
      description: Get a list of all the game characters available in the database.
      operationId: getGameCharacters
      tags:
        - Game
      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.
    parameters:
      - name: key
        in: query
        description: The game character key to filter the response.
        required: false
        schema:
          type: string
        style: form
      - name: name
        in: query
        description: The game character name to filter the response.
        required: false
        schema:
          type: string
        style: form
  /gameseries:
    get:
      description: Gets a list of all the game series available in the database.
      operationId: getGameSeries
      tags:
        - Game
      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.
    parameters:
      - name: key
        in: query
        description: The game series key to filter the response.
        required: false
        schema:
          type: string
        style: form
      - name: name
        in: query
        description: The game series name to filter the response.
        required: false
        schema:
          type: string
        style: form
  /type:
    get:
      description: Gets a list of all the Amiibo types available in the database.
      operationId: getAmiiboTypes
      tags:
        - Amiibo
      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.
    parameters:
      - name: key
        in: query
        description: The Amiibo type key to filter the response.
        required: false
        schema:
          type: string
        style: form
      - name: name
        in: query
        description: The Amiibo type name to filter the response.
        required: false
        schema:
          type: string
        style: form
  /lastupdated:
    get:
      description: Gets a timestamp when the Amiibo data was last updated.
      operationId: getLastUpdated
      tags:
        - Service
      responses:
        '200':
          description: Successful response returning the object that contains the date and time when the database was last updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LastUpdated'
        '400':
          description: A last updated bad request.
        '404':
          description: A last updated not found.
        '500':
          description: Service is not available.
components:
  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