search-api-spec.yaml

openapi: 3.0.0
info:
  description: The SenNet Search API is a thin wrapper of the Elasticsearch API. It handles data indexing and reindexing into the backend Elasticsearch. It also accepts the search query and passes through to the Elasticsearch with data access security check.
  version: 1.3.8
  title: SenNet Search API
  termsOfService: 'https://sennetconsortium.org'
  contact:
    name: SenNet Help Desk
    email: help@sennetconsortium.org
  license:
    name: MIT License
    url: 'https://github.com/sennetconsortium/entity-api/blob/master/license.txt'
servers:
  - url: "https://search.api.sennetconsortium.org/"
security:
  - BearerAuth: [ ]
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: Globus Bearer token to authorize requests
  schemas:
    requestJsonBody:
      type: object
      description: JSON that describes an Elasticsearch [DSL query](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl.html)
    AssayTypeQueryDict:
      type: object
      properties:
        name:
          type: string
    AssayTypeReturnDict:
      type: object
      properties:
        name:
          type: string
        description:
          type: string
        primary:
          type: boolean
    SearchResponse:
      type: object
      description: The response from calls to /search will include objects from indices related for entities, files, or antibodies. Schema elements are documented in [entity-api](https://smart-api.info/ui/0065e419668f3336a40d1f5ab89c6ba3).
tags:
  - name: 'Search API, Elasticsearch'
    description: Operations pertaining to datasets indexed in Elasticsearch


externalDocs:
  description: Elasticsearch API Documentation
  url: https://www.elastic.co/guide/en/sennet_translation/reference/current/search-your-data.html

paths:
  /indices:
    get:
      tags:
        - indices
      summary: Reindex for a given UUID of dataset.  Use this method to obtain a list of valid indices within the search-api endpoint.  These index names are used in some of the subsequent calls made to the endpoint.
      operationId: get-indices
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  indices:
                    example: [ "entities", "portal" ]
                    type: array
                    items:
                      type: string
        "400":
          description: Bad request. A JSON body and appropriate Content-Type header are required in request
        "401":
          description: A valid globus token in the `Authorization` header (Bearer scheme) is required in request
        "403":
          description: "The globus token used in the `Authorization` header doesn't have the right group access permission"

  /search:
    post:
      tags:
        - search
      summary: Executes an Elasticsearch DSL query JSON via POST and returns hits that match the query.
      description: To execute a query, the POST method must provide 1) a request body that specifies an [Elasticsearch Query DSL statement](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-your-data.html) 2) a bearer token in the Authorization header supplied by SenNet. Results are limited to those authorized by the bearer token. Uses the <strong>hm_consortium_entities</strong> index by default.
      operationId: search-post
      requestBody:
        description: A JSON that describes a [DSL query](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl.html). The query will likely be a compound boolean.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/requestJsonBody'
            example: >
              '{
                "query": {
                  "bool": {
                    "must": [
                      {
                        "match_phrase": {
                          "source.group_name": "Vanderbilt TMC"
                        }
                      }
                    ],
                    "filter": [
                      {
                        "match": {
                          "entity_type.keyword": "Sample"
                        }
                      }
                    ]
                  }
                }
              }'
      responses:
        "200":
          description: Returns search hits from backend Elasticsearch that match the query defined in the request JSON
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        "400":
          description: Bad request. A JSON body and appropriate Content-Type header are required in request
        "401":
          description: A valid globus token in the `Authorization` header (Bearer scheme) is required in request
        "403":
          description: "The globus token used in the `Authorization` header doesn't have the right group access permission"

  /{index_name}/search:
    post:
      tags:
        - search_by_index
      summary: Executes an Elasticsearch DSL query JSON via POST and returns hits that match the query. The response is limited to hits against the specified index_name parameter. Values for index_name can be obtained by calling the /indices endpoint.
      description: To execute a query, the POST method must provide 1) a request body that specifies an [Elasticsearch Query DSL statement](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-your-data.html) 2) a bearer token in the Authorization header supplied by SenNet. Results are limited to those authorized by the bearer token. Uses the <strong>hm_consortium_entities</strong> index by default.
      operationId: search-post-by-index
      parameters:
        - name: index_name
          in: path
          description: The name of an existing Elasticsearch index (see the /indices web service call)
          required: true
          schema:
            type: string
      requestBody:
        description: A JSON that describes a [DSL query](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl.html). The query will likely be a compound boolean.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/requestJsonBody'
            example: >
              '{
                "query": {
                  "bool": {
                    "must": [
                      {
                        "match_phrase": {
                          "source.group_name": "Vanderbilt TMC"
                        }
                      }
                    ],
                    "filter": [
                      {
                        "match": {
                          "entity_type.keyword": "Sample"
                        }
                      }
                    ]
                  }
                }
              }'
      responses:
        "200":
          description: Returns search hits from backend Elasticsearch that match the query defined in the request JSON
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        "400":
          description: Bad request. A JSON body and appropriate Content-Type header are required in request
        "401":
          description: A valid globus token in the `Authorization` header (Bearer scheme) is required in request
        "403":
          description: "The globus token used in the `Authorization` header doesn't have the right group access permission"

  /reindex/{identifier}:
    put:
      tags:
        - reindex
      summary: Reindex for a given UUID of dataset
      operationId: reindex
      parameters:
        - name: identifier
          in: path
          description: The unique identifier of collection. This must be a UUID.
          required: true
          schema:
            type: string
      responses:
        "202":
          description: The request has been accepted and reindex is in process

  /mapping:
    get:
      tags:
        - mapping
      summary: Exposes Elasticsearch's `/_mapping` endpoint to return the mapping definitions for the default index
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssayTypeReturnDict'

  /{index_name}/mapping:
    get:
      tags:
        - mapping
      summary: Exposes Elasticsearch's `/_mapping` endpoint to return the mapping definitions for the provided index
      parameters:
        - name: index_name
          in: path
          description: The name of an existing Elasticsearch index (see the /indices web service call)
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
        "404":
          description: The requested index could not be found

  /param-search/{entity_type}:
    get:
      tags:
        - parameterized_search
      summary: Executes an Elasticsearch DSL query JSON via GET and returns hits that match the query.
      parameters:
        - name: entity_type
          in: path
          required: true
          description: The entity type to be returned
          schema:
            type: string
        - name: produce-clt-manifest
          in: query
          description: An optional parameter that, when set to "true", will make the endpoint return a text representation of a manifest file that corresponds with the datasets queried rather than the original response
          required: false
          schema:
            type: string
      description: Searches datasets based on the given parameter entity-type ('donor', 'dataset', 'sample', etc). GET method must provide a bearer token in the Authorization header supplied by HuBMAP. Results are limited to those authorized by the bearer token.  For more detailed information on using this endpoint see [Detailed Param Search Docs](https://docs.hubmapconsortium.org/param-search)
      operationId: param-search-get
      responses:
        '200':
          description: Returns search hits from backend Elasticsearch that match the parameter
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '303':
          description: If the total response payload exceeds 10 MB, the response is returned via an S3 bucket.  A 303 HTTP response code will be returned with the redirect URL where the query can be retrieved.
        '400':
          description: Bad request. A valid entity-type parameter is required in request
        '401':
          description: A valid globus token in the `Authorization` header (Bearer scheme) is required in request
        '403':
          description: The globus token used in the `Authorization` header doesn't have the right group access permission
        '504':
          description: There is a maximum query and response time of 30 seconds.  If the query response takes 30 seconds or longer, a 504 HTTP response code will be returned.