openapi: 3.0.0
info:
  title: IDC Research API
  version: 1.0.0
  description: API for user authentication, document retrieval, and file downloads
servers:
  - url: https://research-api.idc.com/v1
    description: Production environment

paths:
  /login:
    post:
      operationId: userLogin
      summary: User login
      description: Endpoint to login a user
      tags: [Authentication]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                clientId:
                  type: string
                  example: 26ee5865-8960-49a9-bef8-ccc79e9651b1
                secret:
                  type: string
                  example: 63c17198-0a3e-4505-8922-caa107a50c23
      responses:
        '200':
          description: Successful login
          content:
            application/json:
              schema:
                type: object
                properties:
                  authToken:
                    type: string
                    example: eyJhbGci...
              example:
                authToken: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '500': { $ref: '#/components/responses/InternalServerError' }

  /documents:
    get:
      operationId: listAvailableDocuments
      summary: Get page of available documents
      tags: [Documents]
      description: >
        Endpoint to get a page of documents with fixed ordering (newest on the top by publication date).
        The listing will only contain documents that are currently available based on your subscription. 
        To be more specific - the following criteria have to be met for the document to be listed:
        TODAY >= Document.releaseDate
        TODAY >= Document.publicationDate
        TODAY <= Document.retireDate
      security:
        - bearerAuth: []
      parameters:
        - name: lastUpdatedFrom
          in: query
          required: false
          description: "Date-time, if empty `now() - 1 Year` will be used. It will be compared with the document's publicationDate."
          schema:
            type: string
            format: date-time
            example: "2025-01-01T00:00:00Z"
        - name: lastUpdatedTo
          in: query
          required: false
          description: "Date-time, if empty `end of today` will be used. It will be compared with the document's publicationDate."
          schema:
            type: string
            format: date-time
            example: "2025-12-31T23:59:59Z"
        - name: offset
          in: query
          required: false
          description: "Offset for pagination (index of the first document to be retrieved (i.e. a page start document index)), default is 0. It is used to skip the first N documents in the result set."
          schema:
            type: integer
            example: 150
        - name: limit
          in: query
          required: false
          description: "Maximum number of documents to return (i.e. page size), default is 100"
          schema:
            type: integer
            example: 20
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AvailableDocuments'
              example:
                nextOffset: 120
                data:
                  - documentId: "doc-12345"
                    title: "Economic Outlook 2025"
                    subtype: "Market Analysis"
                    authors:
                      - id: "auth-001"
                        name: "Jane Doe"
                    abstractContent: "This document provides a comprehensive overview..."
                    wordCount: 2500
                    pageCount: 12
                    attachments:
                      - name: "report.pdf"
                        format: "PDF"
                        id: "att-001"
                    publicationDate: "2025-01-10T00:00:00Z"
                    releaseDate: "2025-01-01T00:00:00Z"
                    retireDate: "2026-01-01T00:00:00Z"
                    locale: "en-US"
                    price: 1999
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '500': { $ref: '#/components/responses/InternalServerError' }

  /documents/{documentId}:
    get:
      operationId: getDocumentById
      summary: Get document content by documentId
      tags: [Documents]
      description: Endpoint to get document content by documentId
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/documentIdPath'
      responses:
        '200':
          description: Document content
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentFull'
              example:
                metadata:
                  documentId: "lcUS12345678"
                  title: "Economic Outlook 2025"
                  price: 1999
                content: "<h1>Economic Outlook</h1><p>This year will bring...</p>"
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '500': { $ref: '#/components/responses/InternalServerError' }

  /documents/{documentId}/attachments/{attachmentId}:
    get:
      operationId: downloadDocumentAttachment
      summary: Download attachment of specific document
      tags: [Downloads]
      description: Endpoint to download attachment of specific document (including PDF version of the document)
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/documentIdPath'
        - name: attachmentId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Binary file download
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '500': { $ref: '#/components/responses/InternalServerError' }

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  parameters:
    documentIdPath:
      name: documentId
      in: path
      required: true
      schema:
        type: string
        example: "lcUS12345678"

  responses:
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GeneralErrorResponse'
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GeneralErrorResponse'
    Forbidden:
      description: Access denied
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GeneralErrorResponse'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GeneralErrorResponse'
    TooManyRequests:
      description: Too many requests
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GeneralErrorResponse'
    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GeneralErrorResponse'

  schemas:
    GeneralErrorResponse:
      type: object
      required:
        - message
        - details
      properties:
        timestamp:
          description: timestamp (in ISO format) of the error occurrence. Note, this field is not required and may be missing (depending on the source of the error)
          example: "2025-02-15T14:30:00Z"
          type: string
          format: date-time
        message:
          type: string
        details:
          type: string

    Document:
      type: object
      properties:
        documentId:
          type: string
          description: ID used to retrieve the full document and the attachments such as PDF format, PowerPoint or Excel files, if they exist
          example: "lcUS12345678"
        title:
          type: string
          example: "Economic Outlook 2025"
        subtype:
          type: string
          example: "Market Analysis"
        authors:
          type: array
          items:
            $ref: '#/components/schemas/Author'
        abstractContent:
          type: string
          example: "This document provides a comprehensive overview of the economic outlook for 2025..."
        wordCount:
          type: integer
          example: 2500
        pageCount:
          type: integer
          example: 12
        attachments:
          type: array
          items:
            $ref: '#/components/schemas/Attachment'
          description: |
            List all available formats other than the HTML version of the document. 
            Typical formats include PDF, PPTX, XLSX
        publicationDate:
          type: string
          format: date-time
          description: |
            The date of the publication or the last update of the document. 
            The listing of all available documents is sorted by the publicationDate by default
          example: "2025-01-10T00:00:00Z"
        releaseDate:
          type: string
          format: date-time
          description: |
            The date when the document has been made available to the users.
            It might be set in the future indicating that the document has been already published to the website but will become available later.
          example: "2025-01-01T00:00:00Z"
        retireDate:
          type: string
          format: date-time
          description: |
            The date when the document will stop being available to the users.
            It might be set in the future indicating that the document will be removed from access at that date.
          example: "2026-01-01T00:00:00Z"
        locale:
          type: string
          example: "en-US"
        price:
          type: integer
          format: int32
          example: 7000

    DocumentFull:
      type: object
      properties:
        metadata:
          $ref: '#/components/schemas/Document'
        content:
          type: string
          format: html
          example: "<h1>Economic Outlook</h1><p>This year will bring...</p>"

    Author:
      type: object
      properties:
        id:
          type: string
          example: "PRF001234"
        name:
          type: string
          example: "Jane Doe"

    Attachment:
      type: object
      properties:
        name:
          type: string
          example: "report.pdf"
        format:
          type: string
          example: "PDF"
        id:
          type: string
          example: "lcUS12345678"

    AvailableDocuments:
      type: object
      properties:
        count:
          type: integer
          example: 17
          description: number of documents returned (less than or equal to the limit parameter)
        totalCount:
          type: integer
          format: int64
          example: 194
          description: total number of documents available for the given criteria (i.e. lastUpdatedFrom, lastUpdatedTo)
        nextOffset:
          type: integer
          example: 160
          description: index of the next document (i.e. the first document in the next page)
        data:
          type: array
          items:
            $ref: '#/components/schemas/Document'
