Rapportage API specificatie

openapi: 3.0.0
info:
  title: Reporting API
  version: v1
  description: 'For a more detailed explanation on how to use these APIs, read the documentation in which this swagger definition is included. The API exposes a subset of the ElasticSearch API. The ElasticSearch documentation can be found here: https://www.elastic.co/guide/en/elasticsearch/reference/6.4/index.html'
paths:
  /mapping:
    description: 'Returns a list of fields and their type that are available in the application and can be used to send requests. More details about how to interpret the mapping can be found here: https://www.elastic.co/guide/en/elasticsearch/reference/6.4/mapping.html'
    get:
      responses:
        '200':
          description: Returns a list of available fields that can be queried.
        '403':
          description: Forbidden. Make sure the correct certificate and private key are sent with the request.
        '500':
          description: This error can occur for several reasons but the most likely reason is that the API has not been used for several weeks. In that case the API goes to an “inactive” state to reduce resources used in the cloud provider and is reactivated when a request comes in. The first requests will receive a 500 internal server error response while the API is reactivating. This should only take 2-3 minutes. If the issue is not resolved within 5 minutes, please contact support@skryv.com.
  /search:
    post:
      description: 'Make sure to make use of the scrolling API when doing large exports of data. Make use of the `_source` parameter to limit the response to only what is needed. For more information on which queries are supported, see https://www.elastic.co/guide/en/elasticsearch/reference/6.4/query-dsl.html'
      parameters:
        - name: scroll
          in: query
          schema:
            type: string
          example: 1m
          required: false
        - name: query
          in: query
          required: true
          schema:
            type: object
          examples:
            'dossiers grouped by creation date':
              value:
                aggs:
                  range:
                    date_range:
                      field: dossier.createdAt
                      ranges:
                        - key: '2022'
                          to: '2022-12-31'
                        - key: '2023'
                          from: '2023-01-01'
                          to: now/d
                size: 0
            'dossiers filtered by label and document field':
              value:
                query:
                  bool:
                    filter:
                      - query_string:
                          query: dossier.label:*PAAL*
                          default_operator: AND
                      - nested:
                          path: document
                          query:
                            terms:
                              document.aanvraagPVW.hoedanigheidAanvrager.selectedOption:
                                - natuurlijkPersoon
                                - rechtspersoon
                                - houderVanEenVergunning
                      - bool:
                          should:
                            - term:
                                type: dossier
                size: 0
            'sorting on aanvraagdatum':
              value:
                _source:
                  - dossier
                query:
                  bool:
                    filter:
                      - query_string:
                          query: dossier.label:2?-EXAMPLE-*
                          default_operator: AND
                      - bool:
                          should:
                            - term:
                                type: dossier
                sort:
                  - document.aanvraag.aanvraagdatum:
                      order: asc
                      mode: min
                      nested:
                        path: document
                  - dossier.createdAt: asc
                size: 1
                

      responses:
        '200':
          description: Returns either aggregations or a list of dossiers.
        '403':
          description: Forbidden. Make sure the correct certificate and private key are sent with the request.
        '500':
          description: This error can occur for several reasons but the most likely reason is that the API has not been used for several weeks. In that case the API goes to an “inactive” state to reduce resources used in the cloud provider and is reactivated when a request comes in. The first requests will receive a 500 internal server error response while the API is reactivating. This should only take 2-3 minutes. If the issue is not resolved within 5 minutes, please contact support@skryv.com.
  /search/scroll:
    post:
      description: 'Used in exporting large quantities of data. First retrieve a scroll marker using the regular `/search` endpoint by passing the `scroll` query parameter and use the `scroll_id` with this endpoint to continually loop over the results. More details about the scrolling API can be found here: https://www.elastic.co/guide/en/elasticsearch/reference/6.4/search-request-scroll.html'
      parameters:
        - name: query
          in: query
          schema:
            type: object
          examples:
            default:
              value:
                scroll: 1m
                scroll_id: DXF1ZXJ5QW5kRmV0Y2gBAAAAAAAAEmkWd3UwWlM3VlRRNnlfcWd4alJsTUU0dw==
      responses:
        '200':
          description: Returns the next paginated list of dossiers.
        '403':
          description: Forbidden. Make sure the correct certificate and private key are sent with the request.
        '500':
          description: This error can occur for several reasons but the most likely reason is that the API has not been used for several weeks. In that case the API goes to an “inactive” state to reduce resources used in the cloud provider and is reactivated when a request comes in. The first requests will receive a 500 internal server error response while the API is reactivating. This should only take 2-3 minutes. If the issue is not resolved within 5 minutes, please contact support@skryv.com.