FIWARE Entities API

openapi: 3.2.0
info:
  version: '1.0'
  title: FIWARE-NGSI v2 Specification Entities API
  description: 'TODO: Add a description'
servers:
- url: http://orion.lab.fiware.org/
tags:
- name: Entities
paths:
  /v2/entities:
    get:
      description: "Retrieves a list of entities that match different criteria by id, type, pattern matching (either id or type)\nand/or those which match a query or geographical query (see [Simple Query Language](#simple_query_language) and \n[Geographical Queries](#geographical_queries)). A given entity has to match all the criteria to be retrieved\n(i.e., the criteria is combined in a logical AND way). Note that pattern matching query parameters are incompatible\n(i.e. mutually exclusive) with their corresponding exact matching parameters, i.e. `idPattern` with `id` and\n`typePattern` with `type`.\nThe response payload is an array containing one object per matching entity. Each entity follows\nthe JSON entity representation format (described in \"JSON Entity Representation\" section).\nResponse code:\n* Successful operation uses 200 OK\n* Errors use a non-2xx and (optionally) an error payload. See subsection on \"Error Responses\" for\n  more details."
      summary: List Entities
      tags:
      - Entities
      operationId: List Entities
      parameters:
      - name: id
        in: query
        required: false
        description: 'A comma-separated list of elements.

          Retrieve entities whose ID matches one of the elements in the list.

          Incompatible with `idPattern`.'
        schema:
          type: string
      - name: type
        in: query
        required: false
        description: 'comma-separated list of elements.

          Retrieve entities whose type matches one of the elements in the list.

          Incompatible with `typePattern`.'
        schema:
          type: string
      - name: idPattern
        in: query
        required: false
        description: 'A correctly formated regular expression.

          Retrieve entities whose ID matches the regular expression. Incompatible with `id`.'
        schema:
          type: string
      - name: typePattern
        in: query
        required: false
        description: 'A correctly formated regular expression.

          Retrieve entities whose type matches the regular expression. Incompatible with `type`.'
        schema:
          type: string
      - name: q
        in: query
        required: false
        description: 'A query expression, composed of a list of statements

          separated by `;`, i.e., q=statement1;statement2;statement3.

          See [Simple Query Language specification](#simple_query_language).'
        schema:
          type: string
      - name: mq
        in: query
        required: false
        description: 'A query expression for attribute metadata,

          composed of a list of statements separated by `;`, i.e., mq=statement1;statement2;statement3.

          See [Simple Query Language specification](#simple_query_language).'
        schema:
          type: string
      - name: georel
        in: query
        required: false
        description: 'Spatial relationship between matching entities and a

          reference shape. See [Geographical Queries](#geographical_queries).'
        schema:
          type: string
      - name: geometry
        in: query
        required: false
        description: 'Geografical area to which the query is restricted.

          See [Geographical Queries](#geographical_queries).'
        schema:
          type: string
      - name: coords
        in: query
        required: false
        description: 'List of latitude-longitude

          pairs of coordinates separated by '';''. See [Geographical Queries](#geographical_queries).'
        schema:
          type: string
      - name: limit
        in: query
        required: false
        description: Limits the number of entities to be retrieved
        schema:
          type: number
          format: double
      - name: offset
        in: query
        required: false
        description: Establishes the offset from where entities are retrieved
        schema:
          type: number
          format: double
      - name: attrs
        in: query
        required: false
        description: 'Comma-separated list of attribute names whose data

          are to be included in the response.

          The attributes are retrieved in the order specified by this parameter. If this parameter is

          not included, the attributes are retrieved in arbitrary order.

          See "Filtering out attributes and metadata" section for more detail.'
        schema:
          type: string
      - name: metadata
        in: query
        required: false
        description: 'A list of metadata names to include in the response.

          See "Filtering out attributes and metadata" section for more detail.'
        schema:
          type: string
      - name: orderBy
        in: query
        required: false
        description: 'Criteria for ordering results.

          See "Ordering Results" section for details.'
        schema:
          type: string
      - name: options
        in: query
        required: false
        x-enum-elements:
        - name: count
          description: ''
        - name: keyValues
          description: ''
        - name: values
          description: ''
        - name: unique
          description: ''
        description: Options dictionary
        schema:
          type: string
          enum:
          - count
          - keyValues
          - values
          - unique
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ListEntitiesResponse'
              example:
              - type: Room
                id: DC_S1-D41
                temperature:
                  value: 35.6
                  type: Number
                  metadata: {}
              - type: Room
                id: Boe-Idearium
                temperature:
                  value: 22.5
                  type: Number
                  metadata: {}
              - type: Car
                id: P-9873-K
                speed:
                  value: 100
                  type: number
                  metadata:
                    accuracy:
                      value: 2
                      type: Number
                    timestamp:
                      value: '2015-06-04T07:20:27.378Z'
                      type: DateTime
      x-unitTests:
      - request:
          method: GET
          uri: /v2/entities?id=Boe_Idearium&type=Room&idPattern=Bode_.*&typePattern=Room_.*&q=temperature>40&mq=temperature.accuracy<0.9&georel=near&geometry=point&coords=41.390205,2.154007;48.8566,2.3522&limit=20&offset=20&attrs=seatNumber&metadata=accuracy&orderBy=temperature,!speed
        expectedResponse:
          x-allowExtraHeaders: true
          x-bodyMatchMode: RAW
          x-arrayOrderedMatching: false
          x-arrayCheckCount: false
          x-matchResponseSchema: true
          headers:
            Content-Type: application/json
          body: '[ {   "type": "Room",   "id": "DC_S1-D41",   "temperature": {     "value": 35.6,     "type": "Number",     "metadata": {}   } }, {   "type": "Room",   "id": "Boe-Idearium",   "temperature": {     "value": 22.5,     "type": "Number",     "metadata": {}   } }, {   "type": "Car",   "id": "P-9873-K",   "speed": {     "value": 100,     "type": "number",     "metadata": {       "accuracy": {         "value": 2,         "type": "Number"       },       "timestamp": {         "value": "2015-06-04T07:20:27.378Z",         "type": "DateTime"       }     }   } }]'
        x-testShouldPass: true
        x-testEnabled: true
        x-testName: List Entities1
        x-testDescription: "Retrieves a list of entities that match different criteria by id, type, pattern matching (either id or type)\nand/or those which match a query or geographical query (see [Simple Query Language](#simple_query_language) and \n[Geographical Queries](#geographical_queries)). A given entity has to match all the criteria to be retrieved\n(i.e., the criteria is combined in a logical AND way). Note that pattern matching query parameters are incompatible\n(i.e. mutually exclusive) with their corresponding exact matching parameters, i.e. `idPattern` with `id` and\n`typePattern` with `type`.\nThe response payload is an array containing one object per matching entity. Each entity follows\nthe JSON entity representation format (described in \"JSON Entity Representation\" section).\nResponse code:\n* Successful operation uses 200 OK\n* Errors use a non-2xx and (optionally) an error payload. See subsection on \"Error Responses\" for\n  more details."
      x-operation-settings:
        CollectParameters: false
        AllowDynamicQueryParameters: false
        AllowDynamicFormParameters: false
        IsMultiContentStreaming: false
    post:
      description: "The payload is an object representing the entity to be created. The object follows\nthe JSON entity representation format (described in a \"JSON Entity Representation\" section).\nResponse:\n* Successful operation uses 201 Created (if upsert option is not used) or 204 No Content (if\n  upsert option is used). Response includes a `Location` header with the URL of the\n  created entity.\n* Errors use a non-2xx and (optionally) an error payload. See subsection on \"Error Responses\" for\n  more details."
      summary: Create Entity
      tags:
      - Entities
      operationId: Create Entity
      parameters:
      - name: Content-Type
        in: header
        required: true
        description: ''
        schema:
          type: string
      - name: options
        in: query
        required: false
        x-enum-elements:
        - name: keyValues
          description: ''
        - name: upsert
          description: ''
        description: Options dictionary
        schema:
          type: string
          enum:
          - keyValues
          - upsert
      responses:
        '204':
          description: ''
      x-unitTests:
      - request:
          method: POST
          uri: /v2/entities
          headers:
            Content-Type: application/json
          body: '{  "type": "Room",  "id": "Bcn-Welt",  "temperature": {    "value": 21.7  },  "humidity": {    "value": 60  },  "location": {    "value": "41.3763726, 2.1864475",    "type": "geo:point",    "metadata": {      "crs": {        "value": "WGS84"      }    }  }}'
        expectedResponse:
          x-allowExtraHeaders: true
          x-bodyMatchMode: NONE
          x-arrayOrderedMatching: false
          x-arrayCheckCount: false
          x-matchResponseSchema: true
          headers:
            Location: /v2/entities/Bcn-Welt?type=Room
        x-testShouldPass: true
        x-testEnabled: true
        x-testName: Create Entity1
        x-testDescription: "The payload is an object representing the entity to be created. The object follows\nthe JSON entity representation format (described in a \"JSON Entity Representation\" section).\nResponse:\n* Successful operation uses 201 Created (if upsert option is not used) or 204 No Content (if\n  upsert option is used). Response includes a `Location` header with the URL of the\n  created entity.\n* Errors use a non-2xx and (optionally) an error payload. See subsection on \"Error Responses\" for\n  more details."
      x-operation-settings:
        CollectParameters: false
        AllowDynamicQueryParameters: false
        AllowDynamicFormParameters: false
        IsMultiContentStreaming: false
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateEntityRequest'
        required: true
  /v2/entities/{entityId}:
    get:
      description: 'The response is an object representing the entity identified by the ID. The object follows

        the JSON entity representation format (described in "JSON Entity Representation" section).

        This operation must return one entity element only, but there may be more than one entity with the

        same ID (e.g. entities with same ID but different types).

        In such case, an error message is returned, with the HTTP status code set to 409 Conflict.

        Response:

        * Successful operation uses 200 OK

        * Errors use a non-2xx and (optionally) an error payload. See subsection on "Error Responses" for more details.'
      summary: Retrieve Entity
      tags:
      - Entities
      operationId: Retrieve Entity
      parameters:
      - name: entityId
        in: path
        required: true
        description: Id of the entity to be retrieved
        schema:
          type: string
      - name: type
        in: query
        required: false
        description: 'Entity type, to avoid ambiguity in case there are several

          entities with the same entity id.'
        schema:
          type: string
      - name: attrs
        in: query
        required: false
        description: 'Comma-separated list of attribute names whose

          data must be included in the response. The attributes are retrieved in the order specified by

          this parameter. See "Filtering out attributes and metadata" section for more detail.

          If this parameter is not included, the attributes are retrieved in arbitrary order, and all

          the attributes of the entity are included in the response.'
        schema:
          type: string
      - name: metadata
        in: query
        required: false
        description: 'A list of metadata names to include in the response.

          See "Filtering out attributes and metadata" section for more detail.'
        schema:
          type: string
      - name: options
        in: query
        required: false
        x-enum-elements:
        - name: keyValues
          description: ''
        - name: values
          description: ''
        - name: unique
          description: ''
        description: Options dictionary
        schema:
          type: string
          enum:
          - keyValues
          - values
          - unique
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetrieveEntityResponse'
              example:
                type: Room
                id: Bcn_Welt
                temperature:
                  value: 21.7
                  type: Number
                humidity:
                  value: 60
                  type: Number
                location:
                  value: 41.3763726, 2.1864475
                  type: geo:point
                  metadata:
                    crs:
                      value: WGS84
                      type: Text
      x-unitTests: []
      x-operation-settings:
        CollectParameters: false
        AllowDynamicQueryParameters: false
        AllowDynamicFormParameters: false
        IsMultiContentStreaming: false
    delete:
      description: "Delete the entity.\nResponse:\n* Successful operation uses 204 No Content\n* Errors use a non-2xx and (optionally) an error payload. See subsection on \"Error Responses\" for\n  more details."
      summary: Remove Entity
      tags:
      - Entities
      operationId: Remove Entity
      parameters:
      - name: entityId
        in: path
        required: true
        description: Id of the entity to be deleted
        schema:
          type: string
      - name: type
        in: query
        required: false
        description: 'Entity type, to avoid ambiguity in case there are several

          entities with the same entity id.'
        schema:
          type: string
      responses:
        '204':
          description: ''
      x-unitTests: []
      x-operation-settings:
        CollectParameters: false
        AllowDynamicQueryParameters: false
        AllowDynamicFormParameters: false
        IsMultiContentStreaming: false
  /v2/entities/{entityId}/attrs:
    get:
      description: "This request is similar to retreiving the whole entity, however this one omits the `id` and `type`\nfields.\nJust like the general request of getting an entire entity, this operation must return only one\nentity element. If more than one entity with the same ID is found (e.g. entities with\nsame ID but different type), an error message is returned, with the HTTP status code set to\n409 Conflict.\nResponse:\n* Successful operation uses 200 OK\n* Errors use a non-2xx and (optionally) an error payload. See subsection on \"Error Responses\" for\n  more details."
      summary: Retrieve Entity Attributes
      tags:
      - Entities
      operationId: Retrieve Entity Attributes
      parameters:
      - name: entityId
        in: path
        required: true
        description: Id of the entity to be retrieved
        schema:
          type: string
      - name: type
        in: query
        required: false
        description: 'Entity type, to avoid ambiguity in case there are several

          entities with the same entity id.'
        schema:
          type: string
      - name: attrs
        in: query
        required: false
        description: 'Comma-separated list of attribute names whose

          data are to be included in the response. The attributes are retrieved in the order specified

          by this parameter.

          If this parameter is not included, the attributes are retrieved in arbitrary order, and all

          the attributes of the entity are included in the response.

          See "Filtering out attributes and metadata" section for more detail.'
        schema:
          type: string
      - name: metadata
        in: query
        required: false
        description: 'A list of metadata names to include in the response.

          See "Filtering out attributes and metadata" section for more detail.'
        schema:
          type: string
      - name: options
        in: query
        required: false
        x-enum-elements:
        - name: keyValues
          description: ''
        - name: values
          description: ''
        - name: unique
          description: ''
        description: Options dictionary
        schema:
          type: string
          enum:
          - keyValues
          - values
          - unique
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetrieveEntityAttributesResponse'
              example:
                temperature:
                  value: 21.7
                  type: Number
                humidity:
                  value: 60
                  type: Number
                location:
                  value: 41.3763726, 2.1864475
                  type: geo:point
                  metadata:
                    crs:
                      value: WGS84
                      type: Text
      x-unitTests: []
      x-operation-settings:
        CollectParameters: false
        AllowDynamicQueryParameters: false
        AllowDynamicFormParameters: false
        IsMultiContentStreaming: false
    put:
      description: "The request payload is an object representing the new entity attributes. The object follows\nthe JSON entity representation format (described in a \"JSON Entity Representation\" above), except\nthat `id` and `type` are not allowed.\nThe attributes previously existing in the entity are removed and replaced by the ones in the\nrequest.\nResponse:\n* Successful operation uses 204 No Content\n* Errors use a non-2xx and (optionally) an error payload. See subsection on \"Error Responses\" for\n  more details."
      summary: Replace all entity attributes
      tags:
      - Entities
      operationId: Replace all entity attributes
      parameters:
      - name: entityId
        in: path
        required: true
        description: Id of the entity in question.
        schema:
          type: string
      - name: Content-Type
        in: header
        required: true
        description: ''
        schema:
          type: string
      - name: type
        in: query
        required: false
        description: 'Entity type, to avoid ambiguity in case there are several

          entities with the same entity id.'
        schema:
          type: string
      - name: options
        in: query
        required: false
        x-enum-elements:
        - name: keyValues
          description: ''
        description: Operations options
        schema:
          type: string
          enum:
          - keyValues
      responses:
        '204':
          description: ''
      x-unitTests: []
      x-operation-settings:
        CollectParameters: false
        AllowDynamicQueryParameters: false
        AllowDynamicFormParameters: false
        IsMultiContentStreaming: false
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReplaceAllEntityAttributesRequest'
        required: true
    post:
      description: "The request payload is an object representing the attributes to append or update. The object follows\nthe JSON entity representation format (described in \"JSON Entity Representation\" section), except\nthat `id` and `type` are not allowed.\nThe entity attributes are updated with the ones in the payload, depending on\nwhether the `append` operation option is used or not.\n* If `append` is not used: the entity attributes are updated (if they previously exist) or appended\n  (if they don't previously exist) with the ones in the payload.\n* If `append` is used (i.e. strict append semantics): all the attributes in the payload not\n  previously existing in the entity are appended. In addition to that, in case some of the\n  attributes in the payload already exist in the entity, an error is returned.\nResponse:\n* Successful operation uses 204 No Content\n* Errors use a non-2xx and (optionally) an error payload. See subsection on \"Error Responses\" for\n  more details."
      summary: Update or Append Entity Attributes
      tags:
      - Entities
      operationId: Update or Append Entity Attributes
      parameters:
      - name: entityId
        in: path
        required: true
        description: Entity id to be updated
        schema:
          type: string
      - name: Content-Type
        in: header
        required: true
        description: ''
        schema:
          type: string
      - name: type
        in: query
        required: false
        description: 'Entity type, to avoid ambiguity in case there are several

          entities with the same entity id.'
        schema:
          type: string
      - name: options
        in: query
        required: false
        x-enum-elements:
        - name: append
          description: ''
        - name: keyValues
          description: ''
        description: Operations options
        schema:
          type: string
          enum:
          - append
          - keyValues
      responses:
        '204':
          description: ''
      x-unitTests: []
      x-operation-settings:
        CollectParameters: false
        AllowDynamicQueryParameters: false
        AllowDynamicFormParameters: false
        IsMultiContentStreaming: false
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateOrAppendEntityAttributesRequest'
        required: true
    patch:
      description: "The request payload is an object representing the attributes to update. The object follows\nthe JSON entity representation format (described in \"JSON Entity Representation\" section), except\nthat `id` and `type` are not allowed.\nThe entity attributes are updated with the ones in the payload. In addition to that, if one or more\nattributes in the payload doesn't exist in the entity, an error is returned.\nResponse:\n* Successful operation uses 204 No Content\n* Errors use a non-2xx and (optionally) an error payload. See subsection on \"Error Responses\" for\n  more details."
      summary: Update Existing Entity Attributes
      tags:
      - Entities
      operationId: Update Existing Entity Attributes
      parameters:
      - name: entityId
        in: path
        required: true
        description: Id of the entity to be updated
        schema:
          type: string
      - name: Content-Type
        in: header
        required: true
        description: ''
        schema:
          type: string
      - name: type
        in: query
        required: false
        description: 'Entity type, to avoid ambiguity in case there are several

          entities with the same entity id.'
        schema:
          type: string
      - name: options
        in: query
        required: false
        x-enum-elements:
        - name: keyValues
          description: ''
        description: Operations options
        schema:
          type: string
          enum:
          - keyValues
      responses:
        '204':
          description: ''
      x-unitTests: []
      x-operation-settings:
        CollectParameters: false
        AllowDynamicQueryParameters: false
        AllowDynamicFormParameters: false
        IsMultiContentStreaming: false
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateExistingEntityAttributesRequest'
        required: true
components:
  schemas:
    RetrieveEntityResponse:
      title: Retrieve Entity response
      example:
        type: Room
        id: Bcn_Welt
        temperature:
          value: 21.7
          type: Number
        humidity:
          value: 60
          type: Number
        location:
          value: 41.3763726, 2.1864475
          type: geo:point
          metadata:
            crs:
              value: WGS84
              type: Text
      type: object
      properties:
        type:
          description: ''
          example: Room
          type: string
        id:
          description: ''
          example: Bcn_Welt
          type: string
        temperature:
          description: ''
          example:
            value: 21.7
            type: Number
          type: object
        humidity:
          description: ''
          example:
            value: 60
            type: Number
          type: object
        location:
          description: ''
          example:
            value: 41.3763726, 2.1864475
            type: geo:point
            metadata:
              crs:
                value: WGS84
                type: Text
          type: object
      required:
      - type
      - id
      - temperature
      - humidity
      - location
    ListEntitiesResponse:
      title: List Entities response
      example:
        type: Room
        id: DC_S1-D41
        temperature:
          value: 35.6
          type: Number
          metadata: {}
      type: object
      properties:
        type:
          description: ''
          example: Room
          type: string
        id:
          description: ''
          example: DC_S1-D41
          type: string
        temperature:
          description: ''
          example:
            value: 35.6
            type: Number
            metadata: {}
          type: object
        speed:
          description: ''
          example:
            value: 100
            type: number
            metadata:
              accuracy:
                value: 2
                type: Number
              timestamp:
                value: '2015-06-04T07:20:27.378Z'
                type: DateTime
          type: object
      required:
      - type
      - id
    RetrieveEntityAttributesResponse:
      title: Retrieve Entity Attributes response
      example:
        temperature:
          value: 21.7
          type: Number
        humidity:
          value: 60
          type: Number
        location:
          value: 41.3763726, 2.1864475
          type: geo:point
          metadata:
            crs:
              value: WGS84
              type: Text
      type: object
      properties:
        temperature:
          description: ''
          example:
            value: 21.7
            type: Number
          type: object
        humidity:
          description: ''
          example:
            value: 60
            type: Number
          type: object
        location:
          description: ''
          example:
            value: 41.3763726, 2.1864475
            type: geo:point
            metadata:
              crs:
                value: WGS84
                type: Text
          type: object
      required:
      - temperature
      - humidity
      - location
    UpdateOrAppendEntityAttributesRequest:
      title: Update or Append Entity Attributes request
      type: object
      properties:
        ambientNoise:
          description: ''
          example:
            value: 31.5
          type: object
      required:
      - ambientNoise
    ReplaceAllEntityAttributesRequest:
      title: Replace all entity attributes request
      type: object
      properties:
        temperature:
          description: ''
          example:
            value: 25.5
          type: object
        seatNumber:
          description: ''
          example:
            value: 6
          type: object
      required:
      - temperature
      - seatNumber
    CreateEntityRequest:
      title: Create Entity request
      example:
        type: Room
        id: Bcn-Welt
        temperature:
          value: 21.7
        humidity:
          value: 60
        location:
          value: 41.3763726, 2.1864475
          type: geo:point
          metadata:
            crs:
              value: WGS84
      type: object
      properties:
        type:
          description: ''
          example: Room
          type: string
        id:
          description: ''
          example: Bcn-Welt
          type: string
        temperature:
          description: ''
          example:
            value: 21.7
          type: object
        humidity:
          description: ''
          example:
            value: 60
          type: object
        location:
          description: ''
          example:
            value: 41.3763726, 2.1864475
            type: geo:point
            metadata:
              crs:
                value: WGS84
          type: object
      required:
      - type
      - id
      - temperature
      - humidity
      - location
    UpdateExistingEntityAttributesRequest:
      title: Update Existing Entity Attributes request
      type: object
      properties:
        temperature:
          description: ''
          example:
            value: 25.5
          type: object
        seatNumber:
          description: ''
          example:
            value: 6
          type: object
      required:
      - temperature
      - seatNumber