navidrome/api/spec1.yml

openapi: "3.0.0"
info:
  version: 0.3.0
  title: Navidrome API
  description: 'This is heavily based on Aura API: https://auraspec.readthedocs.io/en/latest/api.html'
  contact:
    name: Navidrome
    url: https://navidrome.org
servers:
  - url: /api/v2
security:
  - bearerAuth: []
paths:
  /server:
    get:
      operationId: getServerInfo
      responses:
        '200':
          description: The response’s data key maps to a resource object dictionary representing the server.
          content:
            application/vnd.api+json:
              schema:
                type: object
                required: [data]
                properties:
                  data:
                    $ref: '#/components/schemas/ServerInfo'
        default:
          description: unexpected error
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/JSONAPIErrorResponse'
  /tracks:
    get:
      operationId: getTracks
      parameters:
        - in: query
          name: limit
          schema:
            type: integer
            minimum: 0
            default: 0
      responses:
        '200':
          description: TODO
          content:
            application/vnd.api+json:
              schema:
                type: object
                required: [data]
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Track'
        default:
          description: unexpected error
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/JSONAPIErrorResponse'

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

  schemas:
    ServerInfo:
      type: object
      required: [aura-version, server, server-version, auth-required, features]
      properties:
        aura-version:
          type: string
          description: The version of the AURA spec implemented.
          example: "1.0.0"
        server:
          type: string
          description: The name of the server software.
          example: "navidrome"
        server-version:
          type: string
          description: The version number of the server.
          example: "0.60.0"
        auth-required:
          type: boolean
          description: Whether the user has access to the server.
          example: true
        features:
          type: array
          description: A list of optional features the server supports.
          items:
            type: string
            enum:
              - albums
              - artists
              - images
    JSONAPIResourceObject:
      title: JSON:API Resource Object
      description: |
        A JSON:API-compliant resource object. An inheritable object schema that contains the basic framework of a Resource Object from the JSON:API spec.
        The `attributes`, `relationship`, and `meta` properties are added, as necessary, by the inheriting schema.
      type: object
      required: [type, id]
      properties:
        type:
          $ref: '#/components/schemas/JSONAPIType'
        id:
          $ref: '#/components/schemas/JSONAPIId'

    JSONAPIType:
      title: JSON:API type Member
      description: |
        The `type` member is used to describe resource objects that share common attributes and relationships.
        Note: The type member is required in every resource object throughout requests and responses in JSON:API. There are some cases, such as when POSTing to an endpoint representing heterogeneous data, when the type could not be inferred from the endpoint. However, picking and choosing when it is required would be confusing; it would be hard to remember when it was required and when it was not. Therefore, to improve consistency and minimize confusion, type is always required.
      type: string

    JSONAPIId:
      title: JSON:API id Member
      description: Every resource object MUST contain an id member and a type member (exception-the id member is not required when the resource object originates at the client and represents a new resource to be created on the server). Within a given API, each resource object’s type and id pair MUST identify a single, unique resource.
      type: string

    Track:
      allOf:
        - $ref: '#/components/schemas/JSONAPIResourceObject'
        - type: object
          required: [attributes]
          properties:
            attributes:
              $ref: '#/components/schemas/TrackAttributes'

    TrackAttributes:
      type: object
      required: [title, artist, album, albumartist, track, mimetype, duration, channels, bitrate, size]
      properties:
        title:
          type: string
        artist:
          type: string
        album:
          type: string
        albumartist:
          type: string
        track:
          type: integer
        disc:
          type: integer
        year:
          type: integer
        bpm:
          type: integer
        genre:
          type: string
        recording-mbid:
          type: string
        track-mbid:
          type: string
        comments:
          type: string
        mimetype:
          type: string
        duration:
          type: number
        channels:
          type: integer
        bitrate:
          type: integer
        size:
          type: integer

    JSONAPIErrorResponse:
      title: JSON:API Resource Object
      type: object
      required: [errors]
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/JSONAPIErrorObject'
    JSONAPIErrorObject:
      type: object
      description: 'A JSON-API error object. see: https://jsonapi.org/format/#errors'
      properties:
        id:
          type: string
          description: a unique identifier for this particular occurrence of the problem.
          example: 1
        status:
          type: integer
          description: the HTTP status code applicable to this problem, expressed as a string value.
          example: 400
        code:
          type: string
          description: an application-specific error code, expressed as a string value.
          example: invalid_request
        detail:
          type: string
          description: a human-readable explanation specific to this occurrence of the problem.
          example: First name must contain at least two characters.