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 or Location headers where applicable to retrieve resources. Instead of constructing your own URLs, to keep your client decoupled from implementation details.

Retrieves a list of entities that match different criteria by id, type, pattern matching (either id or type) and/or those which match a query or geographical query (see Simple Query Language and Geographical Queries). A given entity has to match all the criteria to be retrieved (i.e., the criteria is combined in a logical AND way). Note that pattern matching query parameters are incompatible (i.e. mutually exclusive) with their corresponding exact matching parameters, i.e. idPattern with id and typePattern with type. The response payload is an array containing one object per matching entity. Each entity follows the JSON entity representation format (described in "JSON Entity Representation" section). Response code:

• Successful operation uses 200 OK
• Errors use a non-2xx and (optionally) an error payload. See subsection on "Error Responses" for more details.

The payload is an object representing the entity to be created. The object follows the JSON entity representation format (described in a "JSON Entity Representation" section). Response:

• Successful operation uses 201 Created (if upsert option is not used) or 204 No Content (if upsert option is used). Response includes a Location header with the URL of the created entity.
• Errors use a non-2xx and (optionally) an error payload. See subsection on "Error Responses" for more details.

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.

Delete the entity. Response:

• Successful operation uses 204 No Content
• Errors use a non-2xx and (optionally) an error payload. See subsection on "Error Responses" for more details.

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 subsection on "Error Responses" for more details.

The request payload is an object representing the new entity attributes. The object follows the JSON entity representation format (described in a "JSON Entity Representation" above), except that id and type are not allowed. The attributes previously existing in the entity are removed and replaced by the ones in the request. Response:

• Successful operation uses 204 No Content
• Errors use a non-2xx and (optionally) an error payload. See subsection on "Error Responses" for more details.

The request payload is an object representing the attributes to append or 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, depending on whether the append operation option is used or not.

• If append is not used: the entity attributes are updated (if they previously exist) or appended (if they don't previously exist) with the ones in the payload.
• If append is used (i.e. strict append semantics): all the attributes in the payload not previously existing in the entity are appended. In addition to that, in case some of the attributes in the payload already exist in the entity, an error is returned. Response:
• Successful operation uses 204 No Content
• Errors use a non-2xx and (optionally) an error payload. See subsection on "Error Responses" for more details.

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 error payload. See subsection on "Error Responses" for more details.

Returns a JSON object with the attribute data of the attribute. The object follows the JSON representation for attributes (described in "JSON Attribute Representation" section). Response:

• Successful operation uses 200 OK.
• Errors use a non-2xx and (optionally) an error payload. See subsection on "Error Responses" for more details.

The request payload is an object representing the new attribute data. Previous attribute data is replaced by the one in the request. The object follows the JSON representation for attributes (described in "JSON Attribute Representation" section). Response:

• Successful operation uses 204 No Content
• Errors use a non-2xx and (optionally) an error payload. See subsection on "Error Responses" for more details.

Removes an entity attribute. Response:

• Successful operation uses 204 No Content
• Errors use a non-2xx and (optionally) an error payload. See subsection on "Error Responses" for more details.

This operation returns the value property with the value of the attribute.

• If attribute value is JSON Array or Object:
  • If Accept header can be expanded to application/json or text/plain return the value as a JSON with a response type of application/json or text/plain (whichever is the first in Accept header or application/json in case of Accept: */*).
  • Else return a HTTP error "406 Not Acceptable: accepted MIME types: application/json, text/plain"
• If attribute value is a string, number, null or boolean:
  • If Accept header can be expanded to text/plain return the value as text. In case of a string, citation marks are used at the begining and end.
  • Else return a HTTP error "406 Not Acceptable: accepted MIME types: text/plain" Response:
• Successful operation uses 200 OK.
• Errors use a non-2xx and (optionally) an error payload. See subsection on "Error Responses" for more details.

The request payload is the new attribute value.

• If the request payload MIME type is application/json, then the value of the attribute is set to the JSON object or array coded in the payload (if the payload is not a valid JSON document, then an error is returned).
• If the request payload MIME type is text/plain, then the following algorithm is applied to the payload:
  • If the payload starts and ends with citation-marks ("), the value is taken as a string (the citation marks themselves are not considered part of the string)
  • If true or false, the value is taken as a boolean.
  • If null, the value is taken as null.
  • If these first three tests 'fail', the text is interpreted as a number.
  • If not a valid number, then an error is returned and the attribute's value is unchanged. The payload MIME type in the request is specified in the Content-Type HTTP header. Response:
• Successful operation uses 204 No Content
• Errors use a non-2xx and (optionally) an error payload. See subsection on "Error Responses" for more details.

If the values option is not in use, this operation returns a JSON array with the entity types. Each element is a JSON object with information about the type:

• type : the entity type name.
• attrs : the set of attribute names along with all the entities of such type, represented in a JSON object whose keys are the attribute names and whose values contain information of such attributes (in particular a list of the types used by attributes with that name along with all the entities).
• count : the number of entities belonging to that type. If the values option is used, the operation returns a JSON array with a list of entity type names as strings. Results are ordered by entity type in alphabetical order. Response code:
• Successful operation uses 200 OK
• Errors use a non-2xx and (optionally) an error payload. See subsection on "Error Responses" for more details.

This operation returns a JSON object with information about the type:

• attrs : the set of attribute names along with all the entities of such type, represented in a JSON object whose keys are the attribute names and whose values contain information of such attributes (in particular a list of the types used by attributes with that name along with all the entities).
• count : the number of entities belonging to that type. Response code:
• Successful operation uses 200 OK
• Errors use a non-2xx and (optionally) an error payload. See subsection on "Error Responses" for more details.

Returns a list of all the subscriptions present in the system. Response:

• Successful operation uses 200 OK
• Errors use a non-2xx and (optionally) an error payload. See subsection on "Error Responses" for more details.

Creates a new subscription. The subscription is represented by a JSON object as described at the beginning of this section. Response:

• Successful operation uses 201 Created
• Errors use a non-2xx and (optionally) an error payload. See subsection on "Error Responses" for more details.

The response is the subscription represented by a JSON object as described at the beginning of this section. Response:

• Successful operation uses 200 OK
• Errors use a non-2xx and (optionally) an error payload. See subsection on "Error Responses" for more details.

Cancels subscription. Response:

• Successful operation uses 204 No Content
• Errors use a non-2xx and (optionally) an error payload. See subsection on "Error Responses" for more details.

Only the fields included in the request are updated in the subscription. Response:

• Successful operation uses 204 No Content
• Errors use a non-2xx and (optionally) an error payload. See subsection on "Error Responses" for more details.

Lists all the context provider registrations present in the system.

Creates a new context provider registration. This is typically used for binding context sources as providers of certain data. The registration is represented by a JSON object as described at the beginning of this section. Response:

• Successful operation uses 201 Created
• Errors use a non-2xx and (optionally) an error payload. See subsection on "Error Responses" for more details.

The response is the registration represented by a JSON object as described at the beginning of this section. Response:

• Successful operation uses 200 OK
• Errors use a non-2xx and (optionally) an error payload. See subsection on "Error Responses" for more details.

Cancels a context provider registration. Response:

• Successful operation uses 204 No Content
• Errors use a non-2xx and (optionally) an error payload. See subsection on "Error Responses" for more details.

Only the fields included in the request are updated in the registration. Response:

• Successful operation uses 204 No Content
• Errors use a non-2xx and (optionally) an error payload. See subsection on "Error Responses" for more details.

This operation allows to create, update and/or delete several entities in a single batch operation. The payload is an object with two properties:

• actionType, to specify the kind of update action to do: either append, appendStrict, update, delete, or replace.
• entities, an array of entities, each entity specified using the JSON entity representation format (described in the section "JSON Entity Representation"). This operation is split in as many individual operations as entities in the entities vector, so the actionType is executed for each one of them. Depending on the actionType, a mapping with regular non-batch operations can be done:

• append: maps to POST /v2/entities (if the entity does not already exist) or POST /v2/entities/<id>/attrs (if the entity already exists).
• appendStrict: maps to POST /v2/entities (if the entity does not already exist) or POST /v2/entities/<id>/attrs?options=append (if the entity already exists).
• update: maps to PATCH /v2/entities/<id>/attrs.
• delete: maps to DELETE /v2/entities/<id>/attrs/<attrName> on every attribute included in the entity or to DELETE /v2/entities/<id> if no attribute were included in the entity.
• replace: maps to PUT /v2/entities/<id>/attrs. Response:
• Successful operation uses 204 No Content.
• Errors use a non-2xx and (optionally) an error payload. See subsection on "Error Responses" for more details.

The response payload is an Array containing one object per matching entity, or an empty array [] if no entities are found. The entities follow the JSON entity representation format (described in the section "JSON Entity Representation"). The payload may contain the following elements (all of them optional):

• entities: a list of entites to search for. Each element is represented by a JSON object with the following elements:
  • id or idPattern: Id or pattern of the affected entities. Both cannot be used at the same time, but one of them must be present.
  • type or typePattern: Type or type pattern of the entities to search for. Both cannot be used at the same time. If omitted, it means "any entity type".
• attrs: List of attributes to be provided (if not specified, all attributes).
• expression: an expression composed of q, mq, georel, geometry and coords (see "List entities" operation above about this field).
• metadata: a list of metadata names to include in the response. See "Filtering out attributes and metadata" section for more detail. Response code:

• Successful operation uses 200 OK
• Errors use a non-2xx and (optionally) an error payload. See subsection on "Error Responses" for more details.

This operation is intended to consume a notification payload so that all the entity data included by such notification is persisted, overwriting if necessary. This operation is useful when one NGSIv2 endpoint is subscribed to another NGSIv2 endpoint (federation scenarios). The request payload must be an NGSIv2 notification payload. The behaviour must be exactly the same as POST /v2/op/update with actionType equal to append. Response code:

• Successful operation uses 200 OK
• Errors use a non-2xx and (optionally) an error payload. See subsection on "Error Responses" for more details.