# ===----------------------------------------------------------------------===
# 
# 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 containing a list of Amiibo items.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AmiiboWrapper'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/Unavailable'
      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
      tags:
        - Amiibo
      responses:
        '200':
          $ref: '#/components/responses/SuccessTuple'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/Unavailable'
    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':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/Unavailable'
    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':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/Unavailable'
    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':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/Unavailable'
    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':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/Unavailable'
components:
  responses:
    BadRequest:
      description: Response that indicates the service received a bad request.
      content:
        text/plain:
          schema:
            type: string
          example: "Bad request"
    NotFound: 
      description: Response that indicates the service cannot find a requested resource.
      content:
        text/plain:
          schema:
            type: string
          example: "Not found"
    SuccessTuple:
      description: Response that returns a JSON object containing requested `Tuple` data from a resource.
      content: 
        application/json:
          schema:
            $ref: '#/components/schemas/TupleWrapper'
    Unavailable:
      description: Response that indicates the service is unavailable to respond to requests.
      content:
        text/plain:
          schema:
            type: string
          example: "Service unavailable"
  schemas:
# Core Entities
    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:
          $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
    LastUpdated:
      type: object
      properties:
        lastUpdated:
          type: string
          format: date-time
      required:
        - lastUpdated
# Wrapper Entities
    AmiiboWrapper:
      type: object
      properties:
        amiibo:
          oneOf:
            - $ref: '#/components/schemas/Amiibo'
            - $ref: '#/components/schemas/AmiiboList'
      required:
        - amiibo
    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