openapi.yaml

openapi: 3.0.0

info:
  title: Watchlist API
  description: Watchlist API
  version: 5.6.1

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

  responses:
    Unauthorized:
      description: Authorization failure.
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                example: Unauthorized

    BadRequest:
      description: Bad request.
      content:
        application/json:
          schema:
            type: array
            items:
              type: object
              properties:
                value:
                  type: object
                  properties:
                    code:
                      type: string
                      example: WATCHLIST_CREATE_FAILED_SYMBOL_MISSING
                    message:
                      type: string
                      example: Unable to create watchlist, the symbol is missing from at least one entry.
                children:
                  type: array
                  example: []
                  items: {}

    Forbidden:
      description: User is not authorized to use resource.
      content:
        application/json:
          schema:
            type: array
            items:
              type: object
              properties:
                value:
                  type: object
                  properties:
                    code:
                      type: string
                      example: WATCHLIST_CREATE_FAILED_USER_FORBIDDEN
                    message:
                      type: string
                      example: Unable to create watchlist for another user (watchlist user does not match authorized user).
                children:
                  type: array
                  example: []
                  items: {}

    NotFound:
      description: Requested resource not found.
      content:
        application/json:
          schema:
            type: array
            items:
              type: object
              properties:
                value:
                  type: object
                  properties:
                    code:
                      type: string
                      example: WATCHLIST_EDIT_FAILED_NO_WATCHLIST
                    message:
                      type: string
                      example: Unable to edit watchlist, watchlist does not exist.
                children:
                  type: array
                  example: []
                  items: {}

    ServerError:
      description: Server error.
      content:
        application/json:
          schema:
            type: array
            items:
              type: object
              properties:
                value:
                  type: object
                  properties:
                    code:
                      type: string
                      example: REQUEST_GENERAL_FAILURE
                    message:
                      type: string
                      example: An attempt to create watchlist failed for unspecified reason(s).
                children:
                  type: array
                  example: []
                  items: {}

  schemas:
    metadata:
      type: object
      properties:
        server:
          $ref: '#/components/schemas/metadata-server'
        user:
          $ref: '#/components/schemas/metadata-user'
        context:
          $ref: '#/components/schemas/metadata-context'

    metadata-context:
      type: object
      properties:
        id:
          type: string
          example: BARCHART

    metadata-server:
      type: object
      properties:
        name:
          type: string
          example: barchart/watchlist-private-api-main
        description:
          type: string
          example: API for Barchart Watchlist Service
        environment:
          type: string
          example: prod
        semver:
          type: string
          example: 5.6.1

    metadata-user:
      type: object
      properties:
        id:
          type: string
          example: me

    watchlist:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: 81b2d6fa-bb7e-485b-8670-6d0c9330aa21
        context:
          type: string
          example: BARCHART
        name:
          type: string
          example: Watchlist name
        view:
          type: string
          example: main
        entries:
          $ref: '#/components/schemas/entries'
        preferences:
          $ref: '#/components/schemas/preferences'
        user:
          type: string
          example: 113692067
        system:
          $ref: '#/components/schemas/system'

    preferences:
      type: object
      properties:
        sorting:
          type: object
          properties:
            column:
              type: string
              example: symbol
            desc:
              type: boolean
              example: false

    system:
      type: object
      properties:
        sequence:
          type: integer
          example: 1

        timestamp:
          type: string
          example: 1580990379106

    entries:
      type: array
      items:
        $ref: '#/components/schemas/entry'

    entry:
      type: object
      properties:
        symbol:
          type: string
          example: TSLA
        notes:
          type: object
          additionalProperties: {}

servers:
  - url: https://watchlist-test.aws.barchart.com/v1
    description: Hostname for test environment.
  - url: https://watchlist.aws.barchart.com/v1
    description: Hostname for production environment.

tags:
  - name: Watchlist
  - name: Service

paths:
  /service:
    get:
      summary: Returns the version and authorized user of the Barchart Watchlist Service.
      description: Returns the version number of the Barchart Watchlist Service and the user identifier and context of the authorized user (of the JWT).
      tags:
        - Service
      security:
        - JWT: []
      responses:
        '200':
          description: An object describing the remote service and the authorized user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/metadata'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

  /watchlists:
    get:
      summary: Returns watchlists owned by the current user.
      description: Returns watchlists owned by the current user. If the user has no watchlists, an empty array is returned.
      tags:
        - Watchlist
      security:
        - JWT: []
      parameters:
        - in: query
          name: meta
          description: When "true" only metadata is returned (no "entries")
          required: false
          schema:
            type: string
        - name: X-BARCHART-CLIENT-ID
          in: header
          description: An identifier for the connection (used to suppress WebSocket echo).
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: An array of watchlists.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/watchlist'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/ServerError'

    post:
      summary: Creates a new watchlist.
      description: Creates a new watchlist for the current user.
      tags:
        - Watchlist
      security:
        - JWT: []
      parameters:
        - name: X-BARCHART-CLIENT-ID
          in: header
          description: An identifier for the connection (used to suppress WebSocket echo).
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  example: Watchlist name
                context:
                  type: string
                  example: BARCHART
                view:
                  type: string
                  example: main
                entries:
                  $ref: '#/components/schemas/entries'
                preferences:
                  $ref: '#/components/schemas/preferences'
              required:
                - context
                - entries
                - name
      responses:
        '200':
          description: The newly created watchlist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/watchlist'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/ServerError'

  /watchlists/{watchlist}:
    get:
      summary: Reads a single watchlist, owned by the current user.
      description: Returns a single watchlist, owned by the current user. If the user has no watchlists, an empty array is returned.
      tags:
        - Watchlist
      security:
        - JWT: []
      parameters:
        - name: watchlist
          in: path
          required: true
          description: The identifier of the watchlist.
          schema:
            type: string
            format: uuid
            minimum: 1
        - in: query
          name: meta
          description: When "true" only metadata is returned (no "entries")
          required: false
          schema:
            type: string
        - name: X-BARCHART-CLIENT-ID
          in: header
          description: An identifier for the connection (used to suppress WebSocket echo).
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: An array of watchlists (with one or zero items).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/watchlist'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/ServerError'

    delete:
      summary: Deletes a watchlist.
      description: Deletes a watchlist, given the watchlist identitifer.
      tags:
        - Watchlist
      security:
        - JWT: []
      parameters:
        - name: watchlist
          in: path
          required: true
          description: The identifier of the watchlist.
          schema:
            type: string
            format: uuid
            minimum: 1
        - name: X-BARCHART-CLIENT-ID
          in: header
          description: An identifier for the connection (used to suppress WebSocket echo).
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: The identitifer of deleted watchlist.
          content:
            application/json:
              schema:
                type: object
                properties:
                  watchlist:
                    type: string
                    format: uuid
                    example: 81b2d6fa-bb7e-485b-8670-6d0c9330aa21
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'

    put:
      summary: Edits a watchlist.
      description: Edits a watchlist, given the watchlist identitifer.
      tags:
        - Watchlist
      security:
        - JWT: []
      parameters:
        - name: watchlist
          in: path
          required: true
          description: The identifier of the watchlist.
          schema:
            type: string
            format: uuid
            minimum: 1
        - name: X-BARCHART-CLIENT-ID
          in: header
          description: An identifier for the connection (used to suppress WebSocket echo).
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  example: Watchlist name
                view:
                  type: string
                  example: main
                entries:
                  $ref: '#/components/schemas/entries'
                preferences:
                  $ref: '#/components/schemas/preferences'
              required:
                - name
                - context
                - entries
      responses:
        '200':
          description: The newly edited watchlist.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/watchlist'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'

  /watchlists/{watchlist}/preferences:
    put:
      summary: Edit preferences for a watchlist.
      description: Edit watchlist preferences, given the watchlist identitifer.
      tags:
        - Watchlist
      security:
        - JWT: []
      parameters:
        - name: watchlist
          in: path
          required: true
          description: The identifier of the watchlist.
          schema:
            type: string
            format: uuid
            minimum: 1
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/preferences'
      responses:
        '200':
          description: The edited watchlist.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/watchlist'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'

  /watchlists/{watchlist}/symbols:
    put:
      summary: Adds a symbol to a watchlist.
      description: Adds a symbol a watchlist.
      tags:
        - Watchlist
      security:
        - JWT: []
      parameters:
        - name: watchlist
          in: path
          required: true
          description: The identifier of the watchlist.
          schema:
            type: string
            format: uuid
            minimum: 1
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                entry:
                  $ref: '#/components/schemas/entry'
                index:
                  type: integer
                  example: 3
                  description: The index at which the symbol will be inserted
              required:
                - symbol
      responses:
        '200':
          description: The newly edited watchlist.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/watchlist'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'

  /watchlists/{watchlist}/symbols/{symbol}:
    delete:
      summary: Deletes a symbol a watchlist.
      description: Deletes a symbol a watchlist.
      tags:
        - Watchlist
      security:
        - JWT: []
      parameters:
        - name: watchlist
          in: path
          required: true
          description: The identifier of the watchlist.
          schema:
            type: string
            format: uuid
            minimum: 1
        - name: symbol
          in: path
          required: true
          description: A symbol to delete.
          schema:
            type: string
            minimum: 1
        - name: X-BARCHART-CLIENT-ID
          in: header
          description: An identifier for the connection (used to suppress WebSocket echo).
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: A JSON object of edited watchlist.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/watchlist'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'

    put:
      summary: Changes the relative position of a symbol on a watchlist.
      description: Changes the relative position of a symbol on a watchlist.
      tags:
        - Watchlist
      security:
        - JWT: []
      parameters:
        - name: watchlist
          in: path
          required: true
          description: The identifier of the watchlist.
          schema:
            type: string
            format: uuid
            minimum: 1
        - name: symbol
          in: path
          required: true
          description: The symbol to move.
          schema:
            type: string
            minimum: 1
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                from:
                  type: integer
                  example: 3
                  description: The old index.
                to:
                  type: integer
                  example: 5
                  description: The new index.
              required:
                - from
                - to
      responses:
        '200':
          description: The newly edited watchlist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/watchlist'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'