swagger: '2.0'
info:
  title: Data Extraction API
  description: The Data Extraction API offers a robust interface for executing and managing data extraction requests. It allows users to retrieve and monitor data based on specified parameters, providing flexible query options and supporting various output formats. This API integrates seamlessly with data processing workflows, ensuring efficient and reliable data operations.
  version: 1.0.0
  contact:
    name: Benevity API Support
    url: https://benevity.com
    email: api-support@benevity.com
host: api.benevity.org
schemes:
  - https
produces:
  - application/json
tags:
  - name: Extractions
    description: Operations related to data extraction
x-google-endpoints:
  - name: data-api.endpoints.cdp-platform-data-api-export.cloud.goog
    allowCors: true
paths:
  /extractions:
    post:
      tags:
        - Extractions
      summary: Execute data extraction requests
      description: |
        Initiate an extraction request to retrieve data based on specified parameters and criteria.

        **Example request body 1:**
        ```json
        {
          "data": {
            "type": "extraction",
            "attributes": {
              "queries": [
                {
                  "queryName": "ci_budget",
                  "params": [
                    {
                      "paramName": "fiscalYear",
                      "paramValue": "2023",
                      "operator": "="
                    }
                  ]
                }
              ],
              "fileFormat": "csv",
              "companyCode": "1ABC23DEF"
            }
          }
        }
        ```

        **Example request body 2:**
        ```json
        {
          "data": {
            "type": "extraction",
            "attributes": {
              "executeAll": true,
              "fileFormat": "csv",
              "companyCode": "1ABC23DEF"
            }
          }
        }
        ```
      operationId: postExtractions
      parameters:
        - name: extractions
          in: body
          description: The request body containing extraction request information.
          required: true
          schema:
            $ref: '#/definitions/extractionRequestModel'
      x-google-backend:
        address: ${CLOUD_RUN_URI}
        path_translation: APPEND_PATH_TO_ADDRESS
        deadline: 60.0
      responses:
        '200':
          description: Extraction request executed successfully.
          schema:
            $ref: '#/definitions/extractionResponseModel'
          examples:
            application/json:
              data:
                id: abc2345xxxxxxxxxxxxxxxxxdefgh
                attributes:
                  name: Extractions POST method
                  description: To post queries
                  syncQueryData: []
                  asyncQueryData:
                    - queryName: ci_notes_and_attachments
                      executionStatus: InProgress
                    - queryName: ci_budget
                      executionStatus: InProgress
                    - queryName: ci_forms_data_dictionary
                      executionStatus: InProgress
        '400':
          description: Invalid request parameters.
          schema:
            $ref: '#/definitions/errorModel'
          examples:
            application/json:
              errors:
                - status: '400'
                  title: Invalid request
        '401':
          description: Authentication required.
          schema:
            $ref: '#/definitions/errorModel'
          examples:
            application/json:
              errors:
                - status: '401'
                  title: Unauthorized
        '403':
          description: Forbidden
          schema:
            $ref: '#/definitions/errorModel'
          examples:
            application/json:
              errors:
                - status: '403'
                  title: Forbidden
        '500':
          description: Internal server error.
          schema:
            $ref: '#/definitions/errorModel'
          examples:
            application/json:
              errors:
                - status: '500'
                  title: Internal server error
  /extractions/{id}:
    get:
      tags:
        - Extractions
      summary: Retrieve extraction status
      description: Retrieve the status and results of a specific extraction request using its ID.
      operationId: getExtractions
      parameters:
        - name: id
          in: path
          required: true
          type: string
          description: The ID of the extraction request.
      x-google-backend:
        address: ${CLOUD_RUN_URI}
        path_translation: APPEND_PATH_TO_ADDRESS
        deadline: 60.0
      responses:
        '200':
          description: Extraction status retrieved successfully.
          schema:
            $ref: '#/definitions/extractionStatusResponseModel'
          examples:
            application/json:
              data:
                id: 54c31b177a55475abf0e851dd4bf9c37
                attributes:
                  name: Extractions GET method
                  description: To get query status and pre-signed url
                  queryExecutionDetails:
                    - presignedUrls:
                        - https://example.com/presigned-url1
                      executionStatus: Completed
                      queryName: ci_budget
                    - presignedUrls:
                        - https://example.com/presigned-url1
                      executionStatus: Completed
                      queryName: ci_events
                    - executionStatus: InProgress
                      queryName: ci_forms_data_dictionary
                    - executionStatus: InProgress
                      queryName: ci_request_forms
                    - presignedUrls:
                        - https://example.com/presigned-url1
                        - https://example.com/presigned-url2
                      executionStatus: Completed
                      queryName: ci_linked_request_forms
        '400':
          description: Invalid request parameters.
          schema:
            $ref: '#/definitions/errorModel'
          examples:
            application/json:
              errors:
                - status: '400'
                  title: Bad Request
        '401':
          description: Authentication required.
          schema:
            $ref: '#/definitions/errorModel'
          examples:
            application/json:
              errors:
                - status: '401'
                  title: Unauthorized
        '403':
          description: Forbidden
          schema:
            $ref: '#/definitions/errorModel'
          examples:
            application/json:
              errors:
                - status: '403'
                  title: Forbidden
        '500':
          description: Internal server error.
          schema:
            $ref: '#/definitions/errorModel'
          examples:
            application/json:
              errors:
                - status: '500'
                  title: Internal server error
security:
  - jwt_token: []
securityDefinitions:
  jwt_token:
    authorizationUrl: https://benevity.us.auth0.com/authorize
    flow: implicit
    type: oauth2
    x-google-issuer: https://benevity.us.auth0.com/
    x-google-jwks_uri: https://benevity.us.auth0.com/.well-known/jwks.json
    x-google-audiences: api://benevity-api
    description: |
      JWT token for authentication. Please obtain the token from the provided authorization URL.
definitions:
  extractionRequestModel:
    type: object
    properties:
      data:
        type: object
        properties:
          type:
            type: string
            minLength: 1
            enum:
              - extraction
          attributes:
            type: object
            properties:
              queries:
                type: array
                minItems: 1
                items:
                  type: object
                  properties:
                    queryName:
                      type: string
                      description: The name of the query to be executed.
                    params:
                      type: array
                      minItems: 1
                      items:
                        type: object
                        properties:
                          paramName:
                            type: string
                            description: The name of the parameter.
                          paramValue:
                            type: string
                            description: The value of the parameter.
                          operator:
                            type: string
                            enum:
                              - '='
                              - '>'
                              - <
                              - <=
                              - '>='
                              - '!='
                            description: The comparison operator for the parameter.
                        required:
                          - paramName
                          - paramValue
                          - operator
                  required:
                    - queryName
                description: An array of specific query names and parameters to be executed.
              fileFormat:
                type: string
                minLength: 1
                enum:
                  - json
                  - csv
                description: Allowed output file formats. Case insensitive
              executeAll:
                type: boolean
                enum:
                  - true
                  - false
                description: Flag to execute all queries
              companyCode:
                type: string
                minLength: 1
                description: Company Code against which queries are executed
            required:
              - companyCode
        required:
          - type
          - attributes
    required:
      - data
  extractionResponseModel:
    type: object
    properties:
      data:
        type: object
        properties:
          id:
            type: string
            description: The ID of the query execution.
          attributes:
            type: object
            properties:
              name:
                type: string
                description: The name of the query.
              description:
                type: string
                description: A brief description of the query.
              syncQueryData:
                type: array
                items:
                  type: object
                  properties:
                    queryName:
                      type: string
                      description: The name of the synchronous query.
                    queryData:
                      type: array
                      items:
                        type: array
                        items:
                          type: string
                      description: The data retrieved by the query.
                  required:
                    - queryName
                    - queryData
              asyncQueryData:
                type: array
                items:
                  type: object
                  properties:
                    queryName:
                      type: string
                      description: The name of the asynchronous query.
                    executionStatus:
                      type: string
                      enum:
                        - InProgress
                      description: The execution status of the asynchronous query.
                  required:
                    - queryName
                    - executionStatus
            required:
              - name
              - description
        required:
          - id
          - attributes
    required:
      - data
  extractionStatusResponseModel:
    type: object
    properties:
      data:
        type: object
        properties:
          id:
            type: string
            description: The ID of the query execution.
          attributes:
            type: object
            properties:
              name:
                type: string
                description: The name of the query.
              description:
                type: string
                description: A brief description of the query.
              queryExecutionDetails:
                type: array
                items:
                  type: object
                  properties:
                    presignedUrls:
                      type: array
                      items:
                        type: string
                      description: Presigned URLs for query results.
                    executionStatus:
                      type: string
                      enum:
                        - Completed
                        - InProgress
                        - Failed
                      description: The execution status of the query.
                    queryName:
                      type: string
                      description: The name of the executed query.
                  required:
                    - executionStatus
                    - queryName
            required:
              - name
              - description
              - queryExecutionDetails
        required:
          - id
          - attributes
    required:
      - data
  errorModel:
    type: object
    properties:
      errors:
        type: array
        items:
          type: object
          properties:
            status:
              type: string
              description: The HTTP status code applicable to the error.
            title:
              type: string
              description: A human-readable description of the error.
          required:
            - status
            - title