# template for entries
#name:
#  description: |
#    yada yada yada
#  in: {header, path, query, body}
#  required: {true, false}
#  type: {JSON datatype: number, string, boolean, array, object, null}
#
# Note: entries must be in alphabetical order within each section

# variables in header
Content-type-json:
  description: |
    Mime type of the request body.  Must be ``application/json``.
  in: header
  required: true
  type: string

# variables in path

# variables in query
include-in-query:
  description: |
    Disable showing the facet fields. Display count only.
    The default value is ``true``.
  in: query
  required: false
  type: boolean
options-in-query:
  description: |
    Disable aggregating facet fields. Provides a performance
    improvement. The default value is ``false``.
  in: query
  required: false
  type: boolean
type-in-query:
  description: |
    The resource type whose facets you'd like to see listed.
  in: query
  required: false
  type: string

# variables in body
all-projects:
  description: |
    Indicates that an administator wants to include all resources for
    all projects in the search.  The default is ``false``.
  in: body
  required: false
  type: boolean
es-aggregate-obj:
  description: |
    A JSON object containing the aggregation results.  It contains the following
    fields:

    - ``buckets`` - An array of aggregated results (defaults to the top ten
      terms). There is a bucket for each term. Each element of the array
      contains the following fields:

      - ``doc_count`` - Number of times this term appears.
      - ``key`` - The value of this term.

    - ``doc_count_error_upper_bound`` - The upper bound on the error when
      compiling the document count, needed since the count is approximate.
    - ``sum_other_doc_count`` - Since the number of elements in the bucket
      array may be capped (default is ten), the number of all other document
      counts not included in buckets.
  in: body
  required: true
  type: object
es-hits-obj:
  description: |
    A JSON object containing the search results.  It contains the following
    fields:

    - ``hits`` - An array of search results (defaults to the first 25
      documents).  Each element of the array contains the following fields:

      - ``_id`` - Uniquely identifies the resource within its OpenStack context
        (for instance, Glance images use their Image ID)
      - ``_index`` - The service to which the resource belongs (for example,
        searchlight)
      - ``_score`` - The relevance of a given hit.  By default, this is the
        field upon which results are sorted
      - ``_source`` - The document originally indexed, containing all data
        associated with the OpenStack resource.  This field is a map,
        where each key is a field whose value may be a scalar value, a list,
        a nested object, or a list of nested objects.
      - ``_type`` - The OpenStack resource type of the document (for example,
        "OS::Neutron::Net", "OS::Glance::Image")
      - ``_parent`` - *(optional)* When the resource type has a child
        relationship to another resource type, the id of the specific parent
        resource will appear here.
      - ``_routing`` - *(optional)* Included when an Elasticsearch routing
        for the document is explicitly specified.

    - ``max_score`` - The highest ``_score`` of any document that matches the
      query
    - ``total`` - The total number of documents matching the search criteria
  in: body
  required: true
  type: object
es-query:
  description: |
    A JSON object containing the requested query, expressed in the
    `Elasticsearch Query DSL <http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/query-dsl.html>`_.
  in: body
  required: true
  type: object
es-shards-obj:
  description: |
    A JSON object containing the following fields:

    - ``failed`` - Number of shards in which the search could not be performed
    - ``successful`` - Number of shards in which the search was successful
    - ``total`` - The total number of shards involved in processing the query
  in: body
  required: true
  type: object
es-timed-out-field:
  description: |
    Indicates whether the search timed out or not.
  in: body
  required: true
  type: boolean
es-took-field:
  description: |
    The time in milliseconds it took for Elasticsearch to execute the search.
  in: body
  required: true
  type: number
facet-list:
  description: |
    A JSON object pairing resource type names with a list of facets
    supported for that resource type.  Each facet object in the list
    contains the following fields:

    - name - the name of the facet
    - type - the datatype of the facet
    - facet_field - (optional, may be available for some string fields)
      may be used to do an exact term match
  in: body
  required: true
  type: object
multi_match-in-body:
  description: |
    A JSON object containing a ``query`` field whose value is an Elasticsearch
    query string.
  in: body
  required: true
  type: string or array of strings
plugin-list:
  description: |
    List of plugins.  Each element of the list contains the following fields:

    - ``alias-indexing`` - the alias this plugin uses to refer to the
      Elasticsearch index in which documents are created
    - ``alias-searching`` - the alias this plugin uses to refer to the
      Elasticsearch index used for querying documents created by this plugin
    - ``type`` - the document type associated with this plugin
  in: body
  required: true
  type: array
type-in-body:
  description: |
    The name of the resource type or types to which the search should be
    restricted.
  in: body
  required: true
  type: string or array of strings
