# ===----------------------------------------------------------------------===
# 
# 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:
      description: Get a list of all the Amiibo items available in the database.
      operationId: getAmiibos
      responses:
        '200':
          description: Successful response returning the object that contains a list of Amiibo items.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AmiiboWrapper'
        '400':
          description: Bad Amiibo request.
      parameters:
        - name: amiiboSeries
          in: query
          description: The Amiibo series identifier or name to filter the response.
          required: false
          schema:
            type: string
          style: form
        - name: character
          in: query
          description: The game character identifier or name to filter the response.
          required: false
          schema:
            type: string
          style: form
        - name: gameseries
          in: query
          description: The game series identifier or name to filter the response.
          required: false
          schema:
            type: string
          style: form
        - name: id
          in: query
          description: The Amiibo identifier to filter the response.
          required: false
          schema:
            type: string
          style: form
        - name: name
          in: query
          description: The Amiibo name to filter the response.
          required: false
          schema:
            type: string
          style: form
        - name: showgames
          in: query
          description: The flag that indicates whether to include information about related games.
          required: false
          schema:
            type: boolean
          style: form
        - name: showusage
          in: query
          description: The flag that indicates whether to include information about Amiibo usage in related games.
          required: false
          schema:
            type: boolean
          style: form
        - name: type
          in: query
          description: The 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
      responses:
        '200':
          description: Successful response returning the object that contains a list of Amiibo series.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TupleWrapper'
        '400':
          description: Bad Amiibo series request.
        '404':
          description: Amiibo series not found.
        '500':
          description: Service currently 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
      responses:
        '200':
          description: Successful response returning the object that contains a list of game characters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TupleWrapper'
        '400':
          description: Bad game character request.
        '404':
          description: Game character not found.
        '500':
          description: Service currently 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
      responses:
        '200':
          description: Successful response returning the object that contains a list of game series.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TupleWrapper'
        '400':
          description: Bad game series request.
        '404':
          description: Game series not found.
        '500':
          description: Service currently 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
      responses:
        '200':
          description: Successful response returning the object that contains a list of Amiibo types.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TupleWrapper'
        '400':
          description: Bad Amiibo type request.
        '404':
          description: Amiibo type not found.
        '500':
          description: Service currently 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
      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'

components:
  schemas:
    Amiibo:
      type: object
      properties:
        amiiboSeries:
          type: string
        character:
          type: string
        gameSeries:
          type: string
        games3DS:
          type: array
          items:
            $ref: '#/components/schemas/AmiiboGame'
        gamesSwitch:
          type: array
          items:
            $ref: '#/components/schemas/AmiiboGame'
        gamesWiiU:
          type: array
          items:
            $ref: '#/components/schemas/AmiiboGame'
        head:
          type: string
        image:
          type: string
        name:
          type: string
        release:
          type: object
          $ref: '#/components/schemas/AmiiboRelease'
        tail:
          type: string
        type:
          type: string
      required:
        - amiiboSeries
        - character
        - gameSeries
        - head
        - image
        - name
        - release
        - tail
        - type

    AmiiboGame:
      type: object
      properties:
        amiiboUsage:
          type: array
          items:
            $ref: '#/components/schemas/AmiiboUsage'
        gameID:
          type: array
          items:
            type: string
        gameName:
          type: string
      required:
        - gameID
        - gameName

    AmiiboList:
      type: array
      items:
        $ref: '#/components/schemas/Amiibo'

    AmiiboRelease:
      type: object
      properties:
        au:
          type: string
          format: date-time
        eu:
          type: string
          format: date-time
        jp:
          type: string
          format: date-time
        na:
          type: string
          format: date-time

    AmiiboUsage:
      type: object
      properties:
        Usage:
          type: string
        write:
          type: boolean
      required:
        - Usage
        - write

    AmiiboWrapper:
      type: object
      properties:
        amiibo:
          oneOf:
            - $ref: '#/components/schemas/Amiibo'
            - $ref: '#/components/schemas/AmiiboList'
      required:
        - amiibo

    LastUpdated:
      type: object
      properties:
        lastUpdated:
          type: string
          format: date-time
      required:
        - lastUpdated

    Tuple:
      type: object
      properties:
        key:
          type: string
        name:
          type: string
      required:
        - key
        - name

    TupleList:
      type: array
      items:
        $ref: '#/components/schemas/Tuple'

    TupleWrapper:
      type: object
      properties:
        amiibo:
          oneOf:
            - $ref: '#/components/schemas/Tuple'
            - $ref: '#/components/schemas/TupleList'
      required:
        - amiibo