openapi/sources/paths/search/things.yml

# Copyright (c) 2020 Contributors to the Eclipse Foundation
#
# See the NOTICE file(s) distributed with this work for additional
# information regarding copyright ownership.
#
# This program and the accompanying materials are made available under the
# terms of the Eclipse Public License 2.0 which is available at
# http://www.eclipse.org/legal/epl-2.0
#
# SPDX-License-Identifier: EPL-2.0
get:
  summary: Search for things
  description: |-
    This resource can be used to search for things.

    * The query parameter `filter` is not mandatory. If it is not set, the
      result contains all things which the logged in user is allowed to read.

    * The search is case sensitive. In case you don't know how exactly the
      spelling of value of the namespace, name, attribute, feature etc. is, use the *like*
      notation instead of *eq* for filtering.

    * The resource supports sorting and paging. If paging is not explicitly
      specified by means of the `size` option, a default count of `25`
      documents is returned.

    * The internal search index is "eventually consistent".  Consistency with the latest
      thing updates should recover within milliseconds.
  parameters:
    - $ref: '../../parameters/searchFilter.yml'
    - $ref: '../../parameters/namespacesFilter.yml'
    - $ref: '../../parameters/thingFieldsQueryParam.yml'
    - $ref: '../../parameters/timeoutParam.yml'
    - name: option
      in: query
      description: |-
        Possible values for the parameter:

        #### Sort operations

        * ```sort([+|-]{property})```
        * ```sort([+|-]{property},[+|-]{property},...)```

        #### Paging operations

        * ```size({page-size})```  Maximum allowed page size is `200`. Default page size is `25`.
        * ```cursor({cursor-id})```  Start the search from the cursor location. Specify the cursor ID without
        quotation marks. Cursor IDs are given in search responses and mark the position after the last entry of
        the previous search. The meaning of cursor IDs is unspecified and may change without notice.

        The paging option `limit({offset},{count})` is deprecated.
        It may result in slow queries or timeouts and will be removed eventually.

        #### Examples:

        * ```sort(+thingId)```
        * ```sort(-attributes/manufacturer)```
        * ```sort(+thingId,-attributes/manufacturer)```
        * ```size(10)``` return 10 results
        * ```cursor(LOREMIPSUM)```  return results after the position of the cursor `LOREMIPSUM`.

        #### Combine:

        If you need to specify multiple options, when using the swagger UI just write each option in a new line.
        When using the plain REST API programmatically,
        you will need to separate the options using a comma (,) character.

        ```size(200),cursor(LOREMIPSUM)```

        The deprecated paging option `limit` may not be combined with the other paging options `size` and `cursor`.
      required: false
      schema:
        type: string
  tags:
    - Things-Search
  responses:
    '200':
      description: An array of the matching things.
      content:
        application/json:
          schema:
            $ref: '../../schemas/search/searchResultThings.yml'
    '400':
      description: |-
        The request could not be completed. A provided parameter is in a
        wrong format.
      content:
        application/json:
          schema:
            $ref: '../../schemas/errors/advancedError.yml'
    '401':
      description: The request could not be completed due to missing authentication.
      content:
        application/json:
          schema:
            $ref: '../../schemas/errors/advancedError.yml'
    '403':
      description: The request could not be completed due to an invalid authentication.
      content:
        application/json:
          schema:
            $ref: '../../schemas/errors/advancedError.yml'
    '504':
      description: The request ran out of time to execute on the the back-end. Optimize your query and try again.
      content:
        application/json:
          schema:
            $ref: '../../schemas/errors/advancedError.yml'