openapi: 3.0.1
info:
  description: |
    The Delphi Products API for Consumer Analytics.

    Please note: this version of the API is **DEPRECATED** and will be removed in the future. This documentation exists
    for reference only.
  version: '2.1.0'
  title: Products API
servers:
  - description: API v2
    url: /v2
tags:
  - name: Auth
    description: Authentication and authorization-related components

paths:
  ############################################################################
  # YouTube Routes
  ############################################################################

  ############################################################################
  # Spotify Routes – Redacted
  ############################################################################

  ############################################################################
  # Apple Routes – Redacted
  ############################################################################

  ############################################################################
  # Auth Routes
  ############################################################################
  /oauth/token:
    post:
      tags:
        - Auth
      summary: 'get an access token to make authenticated requests'
      deprecated: true
      description: |
        This version of the API is **deprecated**. Please use the `/v3/oauth/token` endpoint instead of this one.
      operationId: delphi_api.v2.views.auth.OAuth2.post
      requestBody:
        description: 'access token request body'
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/authTokenRequestBody'
      responses:
        200:
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/authTokenResponseBody'

        400:
          $ref: '#/components/responses/InvalidInput'
        401:
          $ref: '#/components/responses/Unauthorized'
        500:
          $ref: '#/components/responses/InternalError'

components:
  securitySchemes:
    # Currently Swagger UI does not support the client_id and client_secret as POST body params to
    # the access token endpoint (only in the header). Since our implementation uses the body,
    # this section has been commented out.
    # This note is to save you the trouble of trying to make this work.
    #    oauth2Auth:
    #      type: oauth2
    #      flows:
    #        clientCredentials:
    #          tokenUrl: '/v2/oauth/token'
    #          scopes:
    #            read:files: 'Read data from the files resource'
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      x-bearerInfoFunc: delphi_api.auth.resource_protector.ProxyResourceProtector.decode_token

  responses:
    ##########################################################################
    # Error Responses
    ##########################################################################
    InvalidInput:
      description: Invalid Input Response Body
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/invalidInputResponseBody'
    Unauthorized:
      description: Unauthorized (AuthError) Response Body
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/unauthorizedResponseBody'
    InternalError:
      description: Internal Error Response Body
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/internalErrorResponseBody'


  schemas:
    ##########################################################################
    # Request/Response Body Schemas
    ##########################################################################
    authTokenRequestBody:
      type: object
      properties:
        client_id:
          description: 'Required – `client_id` from identity provider credentials'
          type: string
          example: 'REPLACE_WITH_YOUR_CLIENT_ID'
        client_secret:
          description: 'Required – `client_secret` from identity provider credentials'
          type: string
          example: 'REPLACE_WITH_YOUR_CLIENT_SECRET'
        grant_type:
          description: '(optional) Defaults to `client_credentials` as the only currently supported method'
          type: string
          example: 'client_credentials'
    authTokenResponseBody:
      type: object
      properties:
        access_token:
          type: string
          example: 'EXAMPLE7J0JtkhGZzA6MscSiUH8qYwer...'
        scope:
          description: 'After authorizing, the available scopes are returned in a standard space deliminated format.'
          type: string
          example: 'read:files'
        expires_in:
          description: 'Length in seconds until token expiration.'
          type: number
          example: 86400
        expires_at:
          description: 'The timestamp of the token expiration in the (Unix) epoch format.'
          type: number
          format: int32
          example: 1569612083
        token_type:
          description: 'The token type, currently the only implementation is for `Bearer`.'
          type: string
          example: 'Bearer'
    invalidInputResponseBody:
      type: object
      description: InvalidInput Response Body
      properties:
        code:
          type: string
          example: invalid_input
        description:
          type: object
    unauthorizedResponseBody:
      type: object
      description: Unauthorized (AuthError) Response Body
      properties:
        code:
          type: string
          example: invalid_header
        description:
          type: string
          example: 'Unable to parse authentication token'
    internalErrorResponseBody:
      type: object
      description: Internal Error Response Body
      properties:
        code:
          type: string
          example: internal_error
        description:
          type: string
          example: 'The application encountered an internal error'
        details:
          type: string
          example: '(optional) more specific details)'