FIWARE

opencollection: 1.0.0
info:
  name: FIWARE-NGSI v2 Specification
  version: '1.0'
items:
- info:
    name: API Entry Point
    type: folder
  items:
  - info:
      name: Retrieve API Resources
      type: http
    http:
      method: GET
      url: '{{baseUrl}}/v2'
    docs: 'This resource does not have any attributes. Instead it offers the initial

      API affordances in the form of the links in the JSON body.

      It is recommended to follow the “url” link values,

      [Link](https://tools.ietf.org/html/rfc5988) or Location headers where

      applicable to retrieve resources. Instead of constructing your own URLs,

      to keep your client decoupled from implementation details.'
- info:
    name: Entities
    type: folder
  items:
  - info:
      name: List Entities
      type: http
    http:
      method: GET
      url: '{{baseUrl}}/v2/entities'
      params:
      - name: id
        value: ''
        type: query
        description: 'A comma-separated list of elements.

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

          Incompatible with `idPattern`.'
      - name: type
        value: ''
        type: query
        description: 'comma-separated list of elements.

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

          Incompatible with `typePattern`.'
      - name: idPattern
        value: ''
        type: query
        description: 'A correctly formated regular expression.

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

          Retrieve entities whose type matches the regular expression. Incompatible with `type`.'
      - name: q
        value: ''
        type: query
        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).'
      - name: mq
        value: ''
        type: query
        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).'
      - name: georel
        value: ''
        type: query
        description: 'Spatial relationship between matching entities and a

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

          See [Geographical Queries](#geographical_queries).'
      - name: coords
        value: ''
        type: query
        description: 'List of latitude-longitude

          pairs of coordinates separated by '';''. See [Geographical Queries](#geographical_queries).'
      - name: limit
        value: ''
        type: query
        description: Limits the number of entities to be retrieved
      - name: offset
        value: ''
        type: query
        description: Establishes the offset from where entities are retrieved
      - name: attrs
        value: ''
        type: query
        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.'
      - name: metadata
        value: ''
        type: query
        description: 'A list of metadata names to include in the response.

          See "Filtering out attributes and metadata" section for more detail.'
      - name: orderBy
        value: ''
        type: query
        description: 'Criteria for ordering results.

          See "Ordering Results" section for details.'
      - name: options
        value: ''
        type: query
        description: Options dictionary
    docs: "Retrieves a list of entities that match different criteria by id, type, pattern matching (either id or type)\n\
      and/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 ex"
  - info:
      name: Create Entity
      type: http
    http:
      method: POST
      url: '{{baseUrl}}/v2/entities'
      headers:
      - name: Content-Type
        value: ''
      params:
      - name: options
        value: ''
        type: query
        description: Options dictionary
    docs: "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."
  - info:
      name: Retrieve Entity
      type: http
    http:
      method: GET
      url: '{{baseUrl}}/v2/entities/:entityId'
      params:
      - name: entityId
        value: ''
        type: path
        description: Id of the entity to be retrieved
      - name: type
        value: ''
        type: query
        description: 'Entity type, to avoid ambiguity in case there are several

          entities with the same entity id.'
      - name: attrs
        value: ''
        type: query
        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.'
      - name: metadata
        value: ''
        type: query
        description: 'A list of metadata names to include in the response.

          See "Filtering out attributes and metadata" section for more detail.'
      - name: options
        value: ''
        type: query
        description: Options dictionary
    docs: '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 an'
  - info:
      name: Remove Entity
      type: http
    http:
      method: DELETE
      url: '{{baseUrl}}/v2/entities/:entityId'
      params:
      - name: entityId
        value: ''
        type: path
        description: Id of the entity to be deleted
      - name: type
        value: ''
        type: query
        description: 'Entity type, to avoid ambiguity in case there are several

          entities with the same entity id.'
    docs: "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."
  - info:
      name: Retrieve Entity Attributes
      type: http
    http:
      method: GET
      url: '{{baseUrl}}/v2/entities/:entityId/attrs'
      params:
      - name: entityId
        value: ''
        type: path
        description: Id of the entity to be retrieved
      - name: type
        value: ''
        type: query
        description: 'Entity type, to avoid ambiguity in case there are several

          entities with the same entity id.'
      - name: attrs
        value: ''
        type: query
        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.'
      - name: metadata
        value: ''
        type: query
        description: 'A list of metadata names to include in the response.

          See "Filtering out attributes and metadata" section for more detail.'
      - name: options
        value: ''
        type: query
        description: Options dictionary
    docs: 'This request is similar to retreiving the whole entity, however this one omits the `id` and `type`

      fields.

      Just like the general request of getting an entire entity, this operation must return only one

      entity element. If more than one entity with the same ID is found (e.g. entities with

      same ID but different type), 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'
  - info:
      name: Update or Append Entity Attributes
      type: http
    http:
      method: POST
      url: '{{baseUrl}}/v2/entities/:entityId/attrs'
      headers:
      - name: Content-Type
        value: ''
      params:
      - name: entityId
        value: ''
        type: path
        description: Entity id to be updated
      - name: type
        value: ''
        type: query
        description: 'Entity type, to avoid ambiguity in case there are several

          entities with the same entity id.'
      - name: options
        value: ''
        type: query
        description: Operations options
    docs: "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 exis"
  - info:
      name: Replace all entity attributes
      type: http
    http:
      method: PUT
      url: '{{baseUrl}}/v2/entities/:entityId/attrs'
      headers:
      - name: Content-Type
        value: ''
      params:
      - name: entityId
        value: ''
        type: path
        description: Id of the entity in question.
      - name: type
        value: ''
        type: query
        description: 'Entity type, to avoid ambiguity in case there are several

          entities with the same entity id.'
      - name: options
        value: ''
        type: query
        description: Operations options
    docs: "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."
  - info:
      name: Update Existing Entity Attributes
      type: http
    http:
      method: PATCH
      url: '{{baseUrl}}/v2/entities/:entityId/attrs'
      headers:
      - name: Content-Type
        value: ''
      params:
      - name: entityId
        value: ''
        type: path
        description: Id of the entity to be updated
      - name: type
        value: ''
        type: query
        description: 'Entity type, to avoid ambiguity in case there are several

          entities with the same entity id.'
      - name: options
        value: ''
        type: query
        description: Operations options
    docs: 'The request payload is an object representing the attributes to update. The object follows

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

      that `id` and `type` are not allowed.

      The entity attributes are updated with the ones in the payload. In addition to that, if one or more

      attributes in the payload doesn''t exist in the entity, an error is returned.

      Response:

      * Successful operation uses 204 No Content

      * Errors use a non-2xx and (optionally) an '
- info:
    name: Attributes
    type: folder
  items:
  - info:
      name: Get attribute data
      type: http
    http:
      method: GET
      url: '{{baseUrl}}/v2/entities/:entityId/attrs/:attrName'
      params:
      - name: entityId
        value: ''
        type: path
        description: Id of the entity
      - name: attrName
        value: ''
        type: path
        description: Name of the attribute to be retrieved.
      - name: type
        value: ''
        type: query
        description: 'Entity type, to avoid ambiguity in case there are several

          entities with the same entity id.'
      - name: metadata
        value: ''
        type: query
        description: 'A list of metadata names to include in the response.

          See "Filtering out attributes and metadata" section for more detail.'
    docs: "Returns a JSON object with the attribute data of the attribute. The object follows the JSON\nrepresentation for\
      \ attributes (described in \"JSON Attribute Representation\" section).\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."
  - info:
      name: Update Attribute Data
      type: http
    http:
      method: PUT
      url: '{{baseUrl}}/v2/entities/:entityId/attrs/:attrName'
      headers:
      - name: Content-Type
        value: ''
      params:
      - name: entityId
        value: ''
        type: path
        description: Id of the entity to update
      - name: attrName
        value: ''
        type: path
        description: Attribute name
      - name: type
        value: ''
        type: query
        description: 'Entity type, to avoid ambiguity in case there are several

          entities with the same entity id.'
    docs: "The request payload is an object representing the new attribute data. Previous attribute data\nis replaced by the\
      \ one in the request. The object follows the JSON representation for attributes\n(described in \"JSON Attribute Representation\"\
      \ section).\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."
  - info:
      name: Remove a Single Attribute
      type: http
    http:
      method: DELETE
      url: '{{baseUrl}}/v2/entities/:entityId/attrs/:attrName'
      params:
      - name: entityId
        value: ''
        type: path
        description: Id of the entity.
      - name: attrName
        value: ''
        type: path
        description: Attribute name.
      - name: type
        value: ''
        type: query
        description: 'Entity type, to avoid ambiguity in case there are several

          entities with the same entity id.'
    docs: "Removes an entity attribute.\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."
- info:
    name: Attribute Value
    type: folder
  items:
  - info:
      name: Get Attribute Value
      type: http
    http:
      method: GET
      url: '{{baseUrl}}/v2/entities/:entityId/attrs/:attrName/value'
      params:
      - name: entityId
        value: ''
        type: path
        description: Id of the entity in question
      - name: attrName
        value: ''
        type: path
        description: Name of the attribute to be retrieved.
      - name: type
        value: ''
        type: query
        description: 'Entity type, to avoid ambiguity in case there are several

          entities with the same entity id.'
    docs: "This operation returns the `value` property with the value of the attribute.\n* If attribute value is JSON Array\
      \ or Object:\n  * If `Accept` header can be expanded to `application/json` or `text/plain` return the value as a JSON\
      \ with a\n    response type of application/json or text/plain (whichever is the first in `Accept` header or\n    `application/json`\
      \ in case of `Accept: */*`).\n  * Else return a HTTP error \"406 Not Acceptable: accepted MIME types: application/json,\
      \ text/plain\"\n* If attribute va"
  - info:
      name: Update Attribute Value
      type: http
    http:
      method: PUT
      url: '{{baseUrl}}/v2/entities/:entityId/attrs/:attrName/value'
      headers:
      - name: Content-Type
        value: ''
      params:
      - name: entityId
        value: ''
        type: path
        description: Id of the entity to be updated.
      - name: attrName
        value: ''
        type: path
        description: Attribute name.
      - name: type
        value: ''
        type: query
        description: 'Entity type, to avoid ambiguity in case there are several

          entities with the same entity id.'
    docs: "The request payload is the new attribute value.\n* If the request payload MIME type is `application/json`, then\
      \ the value of the attribute is set to\n  the JSON object or array coded in the payload (if the payload is not a valid\
      \ JSON document,\n  then an error is returned).\n* If the request payload MIME type is `text/plain`, then the following\
      \ algorithm is applied to the\n  payload:\n  * If the payload starts and ends with citation-marks (`\"`), the value\
      \ is taken as a string\n    (the citation marks t"
- info:
    name: Types
    type: folder
  items:
  - info:
      name: List Entity Types
      type: http
    http:
      method: GET
      url: '{{baseUrl}}/v2/types/'
      params:
      - name: limit
        value: ''
        type: query
        description: Limit the number of types to be retrieved.
      - name: offset
        value: ''
        type: query
        description: Skip a number of records.
      - name: options
        value: ''
        type: query
        description: Options dictionary.
    docs: "If the `values` option is not in use, this operation returns a JSON array with the entity types.\nEach element\
      \ is a JSON object with information about the type:\n* `type` : the entity type name.\n* `attrs` : the set of attribute\
      \ names along with all the entities of such type, represented in\n  a JSON object whose keys are the attribute names\
      \ and whose values contain information of such\n  attributes (in particular a list of the types used by attributes with\
      \ that name along with all the\n  entities).\n*"
  - info:
      name: Retrieve entity type
      type: http
    http:
      method: GET
      url: '{{baseUrl}}/v2/types/:entityType'
      params:
      - name: entityType
        value: ''
        type: path
        description: Entity Type
    docs: "This operation returns a JSON object with information about the type:\n* `attrs` : the set of attribute names along\
      \ with all the entities of such type, represented in\n  a JSON object whose keys are the attribute names and whose values\
      \ contain information of such\n  attributes (in particular a list of the types used by attributes with that name along\
      \ with all the\n  entities).\n* `count` : the number of entities belonging to that type.\nResponse code:\n* Successful\
      \ operation uses 200 OK\n* Errors use a "
- info:
    name: Subscriptions
    type: folder
  items:
  - info:
      name: List Subscriptions
      type: http
    http:
      method: GET
      url: '{{baseUrl}}/v2/subscriptions'
      params:
      - name: limit
        value: ''
        type: query
        description: Limit the number of subscriptions to be retrieved
      - name: offset
        value: ''
        type: query
        description: Skip a number of subscriptions
      - name: options
        value: ''
        type: query
        description: Options dictionary
    docs: "Returns a list of all the subscriptions present in the system.\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."
  - info:
      name: Create Subscription
      type: http
    http:
      method: POST
      url: '{{baseUrl}}/v2/subscriptions'
      headers:
      - name: Content-Type
        value: ''
    docs: "Creates a new subscription.\nThe subscription is represented by a JSON object as described at the beginning of\
      \ this section.\nResponse:\n* Successful operation uses 201 Created\n* Errors use a non-2xx and (optionally) an error\
      \ payload. See subsection on \"Error Responses\" for\n  more details."
  - info:
      name: Retrieve Subscription
      type: http
    http:
      method: GET
      url: '{{baseUrl}}/v2/subscriptions/:subscriptionId'
      params:
      - name: subscriptionId
        value: ''
        type: path
        description: subscription Id.
    docs: "The response is the subscription represented by a JSON object as described at the beginning of this\nsection.\n\
      Response:\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."
  - info:
      name: Update Subscription
      type: http
    http:
      method: PATCH
      url: '{{baseUrl}}/v2/subscriptions/:subscriptionId'
      headers:
      - name: Content-Type
        value: ''
      params:
      - name: subscriptionId
        value: ''
        type: path
        description: subscription Id.
    docs: "Only the fields included in the request are updated in the subscription.\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."
  - info:
      name: Delete subscription
      type: http
    http:
      method: DELETE
      url: '{{baseUrl}}/v2/subscriptions/:subscriptionId'
      params:
      - name: subscriptionId
        value: ''
        type: path
        description: subscription Id.
    docs: "Cancels subscription.\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."
- info:
    name: Registrations
    type: folder
  items:
  - info:
      name: List Registrations
      type: http
    http:
      method: GET
      url: '{{baseUrl}}/v2/registrations'
      params:
      - name: limit
        value: ''
        type: query
        description: Limit the number of registrations to be retrieved
      - name: offset
        value: ''
        type: query
        description: Skip a number of registrations
      - name: options
        value: ''
        type: query
        description: Options dictionary
    docs: Lists all the context provider registrations present in the system.
  - info:
      name: Create Registration
      type: http
    http:
      method: POST
      url: '{{baseUrl}}/v2/registrations'
      headers:
      - name: Content-Type
        value: ''
    docs: "Creates a new context provider registration. This is typically used for binding context sources\nas providers of\
      \ certain data.\nThe registration is represented by a JSON object as described at the beginning of this section.\nResponse:\n\
      * Successful operation uses 201 Created\n* Errors use a non-2xx and (optionally) an error payload. See subsection on\
      \ \"Error Responses\" for\n  more details."
  - info:
      name: Retrieve Registration
      type: http
    http:
      method: GET
      url: '{{baseUrl}}/v2/registrations/:registrationId'
      params:
      - name: registrationId
        value: ''
        type: path
        description: registration Id.
    docs: "The response is the registration represented by a JSON object as described at the beginning of this\nsection.\n\
      Response:\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."
  - info:
      name: Update Registration
      type: http
    http:
      method: PATCH
      url: '{{baseUrl}}/v2/registrations/:registrationId'
      headers:
      - name: Content-Type
        value: ''
      params:
      - name: registrationId
        value: ''
        type: path
        description: registration Id.
    docs: "Only the fields included in the request are updated in the registration.\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."
  - info:
      name: Delete Registration
      type: http
    http:
      method: DELETE
      url: '{{baseUrl}}/v2/registrations/:registrationId'
      params:
      - name: registrationId
        value: ''
        type: path
        description: registration Id.
    docs: "Cancels a context provider registration.\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."
- info:
    name: Batch Operations
    type: folder
  items:
  - info:
      name: Update
      type: http
    http:
      method: POST
      url: '{{baseUrl}}/v2/op/update'
      headers:
      - name: Content-Type
        value: ''
      params:
      - name: options
        value: ''
        type: query
        description: Options dictionary
    docs: "This operation allows to create, update and/or delete several entities in a single batch operation.\nThe payload\
      \ is an object with two properties:\n+ `actionType`, to specify the kind of update action to do: either `append`, `appendStrict`,\
      \ `update`,\n  `delete`, or `replace`.\n+ `entities`, an array of entities, each entity specified using the JSON entity\
      \ representation format\n  (described in the section \"JSON Entity Representation\").\nThis operation is split in as\
      \ many individual operations as enti"
  - info:
      name: Query
      type: http
    http:
      method: POST
      url: '{{baseUrl}}/v2/op/query'
      headers:
      - name: Content-Type
        value: ''
      params:
      - name: limit
        value: ''
        type: query
        description: Limit the number of entities to be retrieved.
      - name: offset
        value: ''
        type: query
        description: Skip a number of records.
      - name: orderBy
        value: ''
        type: query
        description: 'Criteria for ordering results.

          See "Ordering Results" section for details.'
      - name: options
        value: ''
        type: query
        description: Options dictionary
    docs: "The response payload is an Array containing one object per matching entity, or an empty array `[]` if \nno entities\
      \ are found. The entities follow the JSON entity representation format\n(described in the section \"JSON Entity Representation\"\
      ).\nThe payload may contain the following elements (all of them optional):\n+ `entities`: a list of entites to search\
      \ for. Each element is represented by a JSON object with the\n  following elements:\n    + `id` or `idPattern`: Id or\
      \ pattern of the affected entities"
  - info:
      name: Notify
      type: http
    http:
      method: POST
      url: '{{baseUrl}}/v2/op/notify'
      headers:
      - name: Content-Type
        value: ''
      params:
      - name: options
        value: ''
        type: query
        description: Options dictionary
    docs: "This operation is intended to consume a notification payload so that all the entity data included by such notification\
      \ is persisted, overwriting if necessary.\nThis operation is useful when one NGSIv2 endpoint is subscribed to another\
      \ NGSIv2 endpoint (federation scenarios). \nThe request payload must be an NGSIv2 notification payload. \nThe behaviour\
      \ must be exactly the same as `POST /v2/op/update` with `actionType` equal to `append`.\nResponse code:\n* Successful\
      \ operation uses 200 OK\n* Errors use a"
bundled: true