openapi: 3.0.0
info:
  title: Personal Web Services API
  description: Documentation for various web services hosted under mono.exhq.dev
  version: 1.0.0

paths:
  /v1/user/{userId}:
    get:
      tags:
        - Discord Lookup
      summary: Look up Discord user information
      description: Retrieves information about a Discord user using their ID
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
          example: "712639419785412668"
      responses:
        '200':
          description: Successful response with user information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DiscordUser'
      servers:
        - url: https://dc-lookup.mono.exhq.dev

  /getreviews:
    get:
      tags:
        - Review System
      summary: Get reviews
      description: Retrieves reviews from the backend review system
      responses:
        '200':
          description: Successful response with reviews
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Review'
      servers:
        - url: https://backendreview.mono.exhq.dev

  /:
    get:
      tags:
        - Song Link Cache
      summary: Get cached song.link data
      description: Cached proxy for song.link API responses with CORS support
      parameters:
        - name: url
          in: query
          required: true
          schema:
            type: string
          example: "spotify:track:6BJHsLiE47Sk0wQkuppqhr"
          description: Encoded song URL or identifier
      responses:
        '200':
          description: Cached song.link response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SongLinkResponse'
      servers:
        - url: http://slcache.mono.exhq.dev

components:
  schemas:
    DiscordUser:
      type: object
      properties:
        id:
          type: string
          example: "712639419785412668"
        created_at:
          type: string
          format: date-time
          example: "2020-05-20T12:14:37.877Z"
        username:
          type: string
          example: "exhq"
        avatar:
          $ref: '#/components/schemas/DiscordAvatar'
        avatar_decoration:
          type: string
          nullable: true
          example: null
        badges:
          type: array
          items:
            type: string
          example: ["HOUSE_BALANCE"]
        accent_color:
          type: string
          nullable: true
          example: null
        global_name:
          type: string
          example: "ECHO 🐈"
        banner:
          $ref: '#/components/schemas/DiscordBanner'
        raw:
          $ref: '#/components/schemas/DiscordRawData'

    DiscordAvatar:
      type: object
      properties:
        id:
          type: string
          example: "93dd1fc1629fb1ec652c68203af4f3f1"
        link:
          type: string
          example: "https://cdn.discordapp.com/avatars/712639419785412668/93dd1fc1629fb1ec652c68203af4f3f1"
        is_animated:
          type: boolean
          example: false

    DiscordBanner:
      type: object
      properties:
        id:
          type: string
          nullable: true
          example: null
        link:
          type: string
          nullable: true
          example: null
        is_animated:
          type: boolean
          example: false
        color:
          type: string
          nullable: true
          example: null

    DiscordRawData:
      type: object
      properties:
        id:
          type: string
          example: "712639419785412668"
        username:
          type: string
          example: "exhq"
        avatar:
          type: string
          example: "93dd1fc1629fb1ec652c68203af4f3f1"
        discriminator:
          type: string
          example: "0"
        public_flags:
          type: integer
          example: 256
        flags:
          type: integer
          example: 256
        banner:
          type: string
          nullable: true
          example: null
        accent_color:
          type: string
          nullable: true
          example: null
        global_name:
          type: string
          example: "ECHO 🐈"
        avatar_decoration_data:
          type: string
          nullable: true
          example: null
        banner_color:
          type: string
          nullable: true
          example: null
        clan:
          type: string
          nullable: true
          example: null

    Review:
      type: object
      properties:
        reviewID:
          type: integer
          example: 1
        discordID:
          type: string
          example: "712653921692155965"
        reviewText:
          type: string
          example: "meow"
        timestamp:
          type: string
          example: "1708902649485"

    SongLinkResponse:
      type: object
      properties:
        entityUniqueId:
          type: string
          example: "SPOTIFY_SONG::6BJHsLiE47Sk0wQkuppqhr"
        userCountry:
          type: string
          example: "US"
        pageUrl:
          type: string
          example: "https://song.link/s/6BJHsLiE47Sk0wQkuppqhr"
        entitiesByUniqueId:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/SongEntity'
        linksByPlatform:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/PlatformLink'

    SongEntity:
      type: object
      properties:
        id:
          type: string
          example: "6BJHsLiE47Sk0wQkuppqhr"
        type:
          type: string
          example: "song"
        title:
          type: string
          example: "From the Start"
        artistName:
          type: string
          example: "Good Kid"
        thumbnailUrl:
          type: string
          example: "https://i.scdn.co/image/ab67616d0000b273e67835d0a5d81fa4f268b513"
        thumbnailWidth:
          type: integer
          example: 640
        thumbnailHeight:
          type: integer
          example: 640
        apiProvider:
          type: string
          example: "spotify"
        platforms:
          type: array
          items:
            type: string
          example: ["spotify"]

    PlatformLink:
      type: object
      properties:
        country:
          type: string
          example: "US"
        url:
          type: string
          example: "https://open.spotify.com/track/6BJHsLiE47Sk0wQkuppqhr"
        entityUniqueId:
          type: string
          example: "SPOTIFY_SONG::6BJHsLiE47Sk0wQkuppqhr"
        nativeAppUriMobile:
          type: string
          example: "spotify:track:6BJHsLiE47Sk0wQkuppqhr"
        nativeAppUriDesktop:
          type: string
          example: "spotify:track:6BJHsLiE47Sk0wQkuppqhr"

tags:
  - name: Discord Lookup
    description: Discord user information lookup service
  - name: Review System
    description: Backend review system for website
  - name: Song Link Cache
    description: Cached proxy for song.link API