openapi: 3.0.0
info:
  title: Lazuli API
  version: 1.0.0

servers:
  - url: http://host[:port]/api

paths:
  /connections:
      get:
        summary: Returns connections by ids
        tags:
          - Connections
        parameters:
          - in: query
            name: ids
            schema:
              type: array
              items:
                type: string
            description: List of connection ids, comma delimited
            required: true
        responses:
          '200':
            description: A JSON array of connections
            content:
              application/json:
                schema:
                  type: object
                  required:
                    - connections
                  properties:
                    connections:
                      type: array
                      items:
                        $ref: '#/components/schemas/ConnectionInfo'
          '400':
            description: Bad Request
          '401':
            description: Unauthorized
  /users/{userId}/connections:
    get:
      summary: Returns all connections for a specified user
      tags:
        - Connections
      parameters:
        - in: path
          name: userId
          schema:
            type: string
          description: The user's id
          required: true
      responses:
        '200':
          description: A JSON array of connections
          content:
            application/json:
              schema:
                type: object
                required:
                  - connections
                properties:
                  connections:
                    type: array
                    items:
                      $ref: '#/components/schemas/ConnectionInfo'
        '401':
          description: Unauthorized
          
  /users/{userId}/recommendations:
    get:
      summary: Returns recommendations for the user from all connections
      tags:
        - Recommendations
      parameters:
        - in: path
          name: userId
          schema:
            type: string
          description: The user's id
          required: true
      responses:
        '200':
          description: A JSON array of media items
          content:
            application/json:
              schema:
                type: object
                required:
                  - recommendations
                properties:
                  recommendations:
                    type: array
                    items:
                      oneOf:
                        - $ref: '#/components/schemas/Song'
                        - $ref: '#/components/schemas/Album'
                        - $ref: '#/components/schemas/Artist'
                        - $ref: '#/components/schemas/Playlist'
                      discriminator:
                        propertyName: type
        '401':
          description: Unauthorized
  
                
components:
  schemas:
    ConnectionInfo:
      type: object
      required:
        - id
        - userId
        - type
      properties:
        id:
          type: string
        userId:
          type: string
        type:
          type: string
          enum: 
            - 'jellyfin'
            - 'youtube-music'
        serverUrl:
          type: string
        serverName:
          type: string
        jellyfinUserId:
          type: string
        username:
          type: string
        youtubeUserId:
          type: string
        profilePicture:
          type: string
    Song:
      type: object
      required:
        - connection
        - id
        - name
        - type
      properties:
        connection:
          type: string
        id:
          type: string
        name:
          type: string
        type:
          type: string
          enum:
            - 'song'
        duration:
          type: number
        thumbnail:
          type: string
        artists:
          type: array
          items:
            type: object
            required:
              - id
              - name
            properties:
              id:
                type: string
              name:
                type: string
        album:
          type: object
          required:
            - id
            - name
          properties:
            id:
              type: string
            name:
              type: string
        createdBy:
          type: object
          required:
            - id
            - name
          properties:
            id:
              type: string
            name:
              type: string
        releaseDate:
          type: string
    Album:
      type: object
      required:
        - connection
        - id
        - name
        - type
      properties:
        connection:
          type: string
        id:
          type: string
        name:
          type: string
        type:
          type: string
          enum:
            - 'album'
        duration:
          type: number
        thumbnail:
          type: string
        artists:
          type: object
          required:
            - id
            - name
          properties:
            id:
              type: string
            name:
              type: string
        releaseDate:
          type: string
    Artist:
      type: object
      required:
        - connection
        - id
        - name
        - type
      properties:
        connection:
          type: string
        id:
          type: string
        name:
          type: string
        type:
          type: string
          enum:
            - 'artist'
        thumbnail:
          type: string
    Playlist:
      type: object
      required:
        - connection
        - id
        - name
        - type
      properties:
        connection:
          type: string
        id:
          type: string
        name:
          type: string
        type:
          type: string
          enum:
            - 'playlist'
        createdBy:
          type: object
          required:
            - id
            - name
          properties:
            id:
              type: string
            name:
              type: string
        thumbnail:
          type: string