FIWARE-NGSI v2 Specification RC-2016_05

DATE: 31 May 2016
This version:
https://telefonicaid.github.io/fiware-orion/api/v2/stable
Latest version:
https://telefonicaid.github.io/fiware-orion/api/v2/latest

Editors

José Manuel Cantera Fonseca (Telefónica I+D), Fermín Galán Márquez (Telefónica I+D), Tobias Jacobs (NEC).

Copyright (c) 2011-2016 Telecom Italia, Telefónica I+D and NEC.

License

This specification is licensed under the FIWARE Open Specification License (implicit patent license).


Abstract

This specification defines the FIWARE-NGSI version 2 API. FIWARE-NGSI v2 is intended to manage the entire lifecycle of context information, including updates, queries, registrations, and subscriptions.

Preface

Status of this document

This specification is the May 2016 release candidate of the NGSIv2 API specification (RC-2016.05). By "release candidate" we mean that only Minor Changes are expected to the API described by this document. Nonetheless new functionalities will be added in the near future, particularly JSON-LD and NGSI9 (context registration) support

In particular, Minor Changes may be of two types:

The work in progress draft of the specification can be found at the following link.


Conformance

This specification describes the "full" compliance level.

However, future iterations of this specification might define optionality in some parts and the compliance level (or roles/profiles) corresponding to them.

Conventions

NGSI version 2 uses camel case (camelCase) syntax for naming properties and related artifacts used by the API. When referring to URIs, as part of HATEOAS patterns, and to mark them appropriately, the suffix _url is added.

Reference Implementations

Specification

Introduction

The FIWARE NGSI (Next Generation Service Interface) API defines

  • a data model for context information, based on a simple information model using the notion of context entities
  • a context data interface for exchanging information by means of query, subscription, and update operations
  • a context availability interface for exchanging information on how to obtain context information (whether to separate the two interfaces is currently under discussion).

Terminology

Context data modelling and exchange

The main elements in the NGSI data model are context entities, attributes and metadata, as shown in the figure below.

NGSI data model

Context Entities

Context entities, or simply entities, are the center of gravity in the FIWARE NGSI information model. An entity represents a thing, i.e., any physical or logical object (e.g., a sensor, a person, a room, an issue in a ticketing system, etc.). Each entity has an entity id.

Furthermore, the type system of FIWARE NGSI enables entities to have an entity type. Entity types are semantic types; they are intended to describe the type of thing represented by the entity. For example, a context entity with id sensor-365 could have the type temperatureSensor.

Each entity is uniquely identified by the combination of its id and type.

Context Attributes

Context attributes are properties of context entities. For example, the current speed of a car could be modeled as attribute current_speed of entity car-104.

In the NGSI data model, attributes have an attribute name, an attribute type, an attribute value and metadata. The attribute name describes what kind of property the attribute value represents of the entity, for example current_speed. The attribute type represents the NGSI value type of the attribute value. Note that FIWARE NGSI has its own type system for attribute values, so NGSI value types are not the same as JSON types. * The attribute value finally contains * the actual data * optional metadata describing properties of the attribute value like e.g. accuracy, provider, or a timestamp

Context Metadata

Context metadata is used in FIWARE NGSI in several places, one of them being an optional part of the attribute value as described above. Similar to attributes, each piece of metadata has: * a metadata name, describing the role of the metadata in the place where it occurs; for example, the metadata name accuracy indicates that the metadata value describes how accurate a given attribute value is * a metadata type, describing the NGSI value type of the metadata value * a metadata value containing the actual metadata

Note that in NGSI it is not foreseen that metadata may contain nested metadata.

MIME Types

The API response payloads in this specification are based on application/json and (for attribute value type operation) text/plain MIME types. Clients issuing HTTP requests with accept types different than those will get a 406 Not Acceptable error.

JSON Entity Representation

An entity is represented by a JSON object with the following syntax:

  • The entity id is specified by the object's id property, whose value is a string containing the entity id.

  • The entity type is specified by the object's type property, whose value is a string containing the entity's type name.

  • Entity attributes are specified by additional properties, whose names are the name of the attribute and whose representation is described in the "JSON Attribute Representation" section below. Obviously, id and type are not allowed to be used as attribute names.

An example of this syntax in shown below:

{
  "id": "entityID",
  "type": "entityType",
  "attr_1": <val_1>,
  "attr_2": <val_2>,
  ...
  "attr_N": <val_N>
}

The normalized representation of entities always include id, type and the properties that represent attributes. However, simplified or partial representations (see the "Partial Representations" section below) may leave some of them out. The specification of each operation includes details about what representation is expected as input or what representation will be provided (rendered) as output.

JSON Attribute Representation

An attribute is represented by a JSON object with the following syntax:

  • The attribute value is specified by the value property, whose value may be any JSON datatype.

  • The attribute NGSI type is specified by the type property, whose value is a string containing the NGSI type.

  • The attribute metadata is specified by the metadata property. Its value is another JSON object which contains a property per metadata element defined (the name of the property is the name of the metadata element). Each metadata element, in turn, is represented by a JSON object containing the following properties:

  • value: Its value contains the metadata value, which may correspond to any JSON datatype.

  • type: Its value contains a string representation of the metadata NGSI type.

An example of this syntax in shown below:

{
  "value": <...>,
  "type": <...>,
  "metadata": <...>
}

Simplified Entity Representation

There are two representation modes that must be supported by implementations. These representation modes allow to generate simplified representations of entities.

  • keyValues mode. This mode represents the entity attributes by their values only, leaving out the information about type and metadata. See example below.
{
  "id": "R12345",
  "type": "Room",
  "temperature": 22
}
  • values mode. This mode represents the entity as an array of attribute values. Information about id and type is left out. See example below. The order of the attributes in the array is specified by the attrs URI param (e.g. attrs=branch,colour,engine). If attrs is not used, the order is arbitrary.
[ 'Ford', 'black', 78.3 ]
  • unique mode. This mode is just like values mode, except that values are not repeated.

Partial Representations

Some operations use partial representation of entities:

  • id and type are not allowed in update operations, as they are immutable properties.

  • In some cases, not all the attributes of the entity are shown, e.g. a query selecting a subset of the entity attributes.

  • Attribute/metadata value may be omitted in requests, meaning that the attribute/metadata has null value. In responses, the value is always present.

  • Attribute metadata may be omitted in requests, meaning that there are no metadata elements associated to the attribute. In responses, this property is set to {} if the attribute doesn't have any metadata.

Special Attribute Types

Generally speaking, user-defined attribute types are informative; they are processed by the NGSIv2 server in an opaque way. Nonetheless, the types described below are used to convey a special meaning:

  • DateTime: identifies dates, in ISO8601 format. These attributes can be used with the query operators greater-than, less-than, greater-or-equal, less-or-equal and range. For instance (only the referred entity attribute is shown):
{
  "timestamp": {
    "value": "2017-06-17T07:21:24.238Z",
    "type: "DateTime"
  }
}

Virtual Attributes

There are entity properties that are not directly modifiable by NGSIv2 clients, but that can be rendered by NGSIv2 servers to provide extra information. From a representation point of view, they are just like regular attributes, with name, value and type.

Virtual attributes are not rendered by default. In order to render a specific attribute, add its name to the options URL parameter.

The list of virtual attributes is as follows: dateCreated (type: DateTime): entity creation date as an ISO 8601 string. dateModified (type: DateTime): entity modification date as an ISO 8601 string.

Like regular attributes, they can be used in attrs, q filters and orderBy. However, they cannot be used in resource URLs.

Field syntax restrictions

Fields used as identifiers in the NGSIv2 API follow special rules regarding allowed syntax. These rules apply to:

  • Entity id
  • Entity type
  • Attribute name
  • Attribute type
  • Metadata name
  • Metadata type

The rules are:

  • Allowed characters are the ones in the plain ASCII set, except the following ones: control characters, whitespace, &, ?, / and #.
  • Maximum field length is 256 characters.
  • Minimum field length is 1 character.

In addition to the above rules, given NGSIv2 server implementations could add additional syntactical restrictions in those or other fields, e.g., to avoid cross script injection attacks.

In case a client attempts to use a field that is invalid from a syntax point of view, the client gets a "Bad Request" error response, explaining the cause.

Attribute names restrictions

The following strings must not be used as attribute names:

  • id, as it would conflict with the field used to represent entity id.

  • type, as it would conflict with the field used to represent entity type.

  • geo:distance, as it would conflict with the string used in orderBy for proximity to center point.

  • Virtual attribute names (see specific section on "Virtual Attributes")

Ordering Results

Operations that retrieve lists of entities permit the orderBy URI parameter to specify the attributes or properties to be be used as criteria when ordering results. The value of orderBy can be:

  • The keyword geo:distance to order results by distance to a reference geometry when a "near" (georel=near) spatial relationship is used.

  • A comma-separated list of attributes (including virtual attributes), e.g. temperature,!humidity. Results are ordered by the first attribute. On ties, the results are ordered by the second attribute and so on. A "!" before the attribute name means that the order is reversed.

Error Responses

If present, the error payload is a JSON object including the following fields:

  • error (required, string): a textual description of the error.
  • description (optional, string): additional information about the error.

All NGSIv2 server implementations must use the following HTTP response codes and error texts. However, the particular text used for description field is an implementation specific aspect.

Error list (HTTP response code in parenthesis):

  • ParseError (400). The incoming JSON payload cannot be parsed.
  • BadRequest (400). The incoming request is invalid in this context.
  • NotFound (404). The resource (entity, subscription, etc.) referred in the request has not been found.
  • TooManyResults (409). There are several results that match with the resource identification used in the request.
  • ContentLengthRequired (411). Zero/No Content-Length in PUT/POST/PATCH request.
  • RequestEntityTooLarge (413). Payload is too large.
  • UnsupportedMediaType (415). Request content type is not supported.
  • InvalidModification (422). Some piece of information is missing in payload.
  • NotSupportedQuery (422). The implementation does not support the query issued.
  • NoResourcesAvailable (413). There are no server resources to fulfill the client request.

New error codes may be defined in new iterations of this specification.

Geospatial properties of entities

The geospatial properties of a context entity can be represented by means of regular context attributes. The provision of geospatial properties enables the resolution of geographical queries.

Two different syntaxes must be supported by compliant implementations:

  • Simple Location Format. It is meant as a very lightweight format for developers and users to quickly and easily add to their existing entities.

  • GeoJSON. GeoJSON is a geospatial data interchange format based on the JavaScript Object Notation (JSON). GeoJSON provides greater flexibility allowing the representation of point altitudes or even more complex geospatial shapes, for instance multi geometries.

Client applications are responsible for defining which entity attributes convey geospatial properties (by providing an appropriate NGSI attribute type). Typically this is an entity attribute named location, but nothing prevents use cases where an entity contains more than one geospatial attribute. For instance, locations specified at different granularity levels or provided by different location methods with different accuracy. Nonetheless, it is noteworthy that spatial properties need special indexes which can be under resource constraints imposed by backend databases. Thus, implementations may raise errors when spatial index limits are exceeded. The recommended HTTP status code for those situations is 413, Request entity too large, and the reported error on the response payload must be NoResourcesAvailable.

Simple Location Format

Simple Location Format supports basic geometries ( point, line, box, polygon ) and covers the typical use cases when encoding geographical locations. It has been inspired by GeoRSS Simple.

It is noteworthy that the Simple Location Format is not intended to represent complex positions on Earth surface. For instance, applications that require to capture altitude coordinates will have to use GeoJSON as representation format for the geospatial properties of their entities.

A context attribute representing a location encoded with the Simple Location Format must conform to the following syntax:

  • The attribute type must be one of the following values: (geo:point, geo:line, geo:box or geo:polygon).
  • The attribute value must be a list of coordinates. By default, coordinates are defined using the WGS84 Lat Long, EPSG::4326 coordinate reference system (CRS), with latitude and longitude units of decimal degrees. Such coordinate list allow to encode the geometry specified by the type attribute and are encoded according to the specific rules defined below:

  • Type geo:point: the attribute value must contain a string containing a valid latitude-longitude pair, separated by comma.

  • Type geo:line: the attribute value must contain a string array of valid latitude-longitude pairs. There must be at least two pairs.
  • Type geo:polygon: the attribute value must contain a string array of valid latitude-longitude pairs. There must be at least four pairs, with the last being identical to the first (so a polygon has a minimum of three actual points). Coordinate pairs should be properly ordered so that the line segments that compose the polygon remain on the outer edge of the defined area. For instance, the following path, [0,0], [0,2], [2,0], [2, 2], is an example of an invalid polygon definition. Implementations should raise an error when none of the former conditions are met by input data.
  • Type geo:box: A bounding box is a rectangular region, often used to define the extents of a map or a rough area of interest. A box is represented by a two-length string array of latitude-longitude pairs. The first pair is the lower corner, the second is the upper corner.

Note: Circle geometries are not supported, as the literature describes different shortcomings for implementations.

The examples below illustrate the referred syntax:

{
  "location": {
    "value": "41.3763726, 2.186447514",
    "type": "geo:point"
  }
}
{
  "location": {
    "value": [
      "40.63913831188419, -8.653321266174316",
      "40.63881265804603, -8.653149604797363"
    ],
    "type": "geo:box"
  }
}

GeoJSON

A context attribute representing a location encoded using GeoJSON must conform to the following syntax:

  • The NGSI type of the attribute must be geo:json.
  • The attribute value must be a valid GeoJSON object. It is noteworthy that longitude comes before latitude in GeoJSON coordinates.

The example below illustrates the usage of GeoJSON. More GeoJSON examples can be found in GeoJSON IETF Spec. Additionally, the following GeoJSON Tutorial might be useful in understanding the format.

{
  "location": {
    "value": {
      "type": "Point",
      "coordinates": [2.186447514, 41.3763726]
    },
    "type": "geo:json"
  }
}

Simple Query Language

The Simple Query Language provides a simplified syntax to retrieve entities which match a set of conditions. A query is composed by a list of statements separated by the ';' character. Each statement express a matching condition. The query returns all the entities that match all the matching conditions (AND logical operator).

There are two kinds of statements: unary statements and binary statements.

Binary statements are composed by an attribute name (e.g. "temperature"), an operator and a value (whose format depends on the operator), e.g.:

temperature==50
temperature<=20

The list of operators (and the format of the values they use) is as follows:

  • Equal: ==. This operator accepts the following types of right-hand side:
    • Single element, e.g. temperature==40. For an entity to match, it must contain an attribute with that exact name (temperature) and value (40).
    • A list of comma-separated values, e.g. color==black,red. For an entity to match, it must contain an attribute with that name and the value of the attribute must be any of the values in the list (OR clause). E.g. entities with an attribute named color, whose value is black are a match, while entities with an attribute named color but whose value is white do not match.
    • A range, specified as a minimum and a maximum, separated by .., e.g. temperature==10..20. For an entity to match, it must contain an attribute with that name (temperature), and its value must be in the interval between the minimum and maximum of the range (both included). Ranges can only be used with attributes that represent dates (in ISO8601 format), numbers or strings.
  • Unequal: !=. This operator accepts the following types of right-hand side:
    • Single element, e.g. temperature!=41. For an entity to match, it must contain an attribute with that exact name (temperature) and whose value is not that exact value (41).
    • A list of comma-separated values, e.g. color!=black,red. For an entity to match, it must contain an attribute with that name, and whose value is not any of the values in the list (AND clause). Eg. entities whose attribute color is set to black will not match, while entities whose attribute color is set to white will match.
    • A range, specified as a minimum and maximum separated by .., e.g. temperature!=10..20. For an entity to match, it must contain an attribute with that exact name (temperature) and whose value is not in the interval between the minimum and the maximum (both included). Ranges can only be used with attributes that represent dates (in ISO8601 format), numbers or strings.
  • Greater than: >. The right-hand side must be a single element, e.g. temperature>42. For an entity to match, it must contain an attribute with that exact name (temperature) and whose value is strictly greater than that value (42). This operation is only valid for attributes of type date, numbers or strings (used with attributes of other types may lead to unpredictable results).
  • Less than: <. The right-hand side must be a single element, e.g. temperature<43. For an entity to match, it must contain an attribute with that exact name (temperature) and whose value is strictly less than that value (43). This operation is only valid for attributes of type date, numbers or strings (used with attributes of other types may lead to unpredictable results).
  • Greater or equal than: >=. The right-hand side must be a single element, e.g. temperature>=44. For an entity to match, it must contain an attribute with that exact name (temperature) and whose value is greater than or equal to that value (44). This operation is only valid for attributes of type date, numbers or strings (used with attributes of other types may lead to unpredictable results).
  • Less or equal than: <=. The right-hand side must be a single element, e.g. temperature<=45. For an entity to match, it must contain an attribute with that exact name (temperature) and whose value is less than or equal to that value (45). This operation is only valid for attributes of type date, numbers or strings (used with attributes of other types may lead to unpredictable results).
  • Match pattern: ~=. The value matches a given pattern, expressed as a regular expression, e.g. color~=ow. For an entity to match, it must contain an attribute with that exact name (color), and whose value matches the string in the right-hand side, 'ow' in this example (brown and yellow would match, black and white would not). This operation is only valid for attributes of type string.

The symbol : can be used instead of ==.

In the case of equal or unequal, if s string to match includes a ,, you can use simple quote (') to disable the special meaning of the comma, e.g: color=='light,green','deep,blue'. The first example would match a color with the exact value 'light,green' OR 'deep,blue'.

Unary negatory statements use the unary operator !, while affirmative unary statements use no operator at all. The unary statements are used to check for the existence of attribute. E.g. temperature matches entities that have an attribute called 'temperature' (no matter its value), while !temperature matches entities that do not have a temperature called 'attribute'.

Geographical Queries

Geographical queries are specified using the following parameters:

georel is intended to specify a spatial relationship (a predicate) between matching entities and a reference shape (geometry). It is composed of a token list separated by ';'. The first token is the relationship name, the rest of the tokens (if any) are modifiers which provide more information about the relationship. The following values are recognized:

  • georel=near. The near relationship means that matching entities must be located at a certain threshold distance to the reference geometry. It supports the following modifiers:
  • maxDistance. Expresses, in meters, the maximum distance at which matching entities must be located.
  • minDistance. Expresses, in meters, the minimum distance at which matching entities must be located.
  • georel=coveredBy. Denotes that matching entities are those that exist entirely within the reference geometry. When resolving a query of this type, the border of the shape must be considered to be part of the shape.
  • georel=intersects. Denotes that matching entities are those intersecting with the reference geometry.
  • georel=equals. The geometry associated to the position of matching entities and the reference geometry must be exactly the same.
  • georel=disjoint. Denotes that matching entities are those not intersecting with the reference geometry.

geometry allows to define the reference shape to be used when resolving the query. The following geometries (see Simple Location Format) must be supported:

  • geometry=point, defines a point on the Earth surface.
  • geometry=line, defines a polygonal line.
  • geometry=polygon, defines a polygon.
  • geometry=box, defines a bounding box.

coords must be a string containing a semicolon-separated list of pairs of geographical coordinates in accordance with the geometry specified and the rules mandated by the Simple Location Format:

  • geometry=point. coords contains a pair of WGS-84 geo-coordinates.
  • geometry=line. coords contains a list of pairs of WGS-84 geo-coordinates.
  • geometry=polygon. coords is composed by at least four pairs of WGS-84 geo-coordinates.
  • geometry=box. coords is composed by two pairs of WGS-84 geo-coordinates.

Examples:

georel=near;maxDistance:1000&geometry=point&coords=-40.4,-3.5. Matching entities must be located (at most) 1000 meters from the reference point.

georel=near;minDistance:5000&geometry=point&coords=-40.4,-3.5. Matching entities must be (at least) 5000 meters from the reference point.

georel=coveredBy&geometry=polygon&coords=25.774,-80.190;18.466,-66.118;32.321,-64.757;25.774,-80.190 Matching entities are those located within the referred polygon.

Query Resolution

If an implementation is not able to resolve a geographical query, the HTTP Status code of the response must be 422, Unprocessable Entity. The error name, present in the error payload, must be NotSupportedQuery.

When resolving geographical queries, through the Simple Query Language, the API implementation is responsible for determining which entity attribute contains the geographical location to be used for matching purposes. To this aim, the following rules must be followed:

  • If an entity has no attribute corresponding to a location (encoded as GeoJSON or the Simple Location Format), then such an entity has not declared any geospatial property and will not match any geographical query.

  • If an entity only exposes one attribute corresponding to a location, then such an attribute will be used when resolving geographical queries.

  • If an entity exposes more than one location, then the attribute containing a metadata property named defaultLocation, with boolean value true will be taken as the reference location used for resolving geographical queries.

  • If there is more than one attribute exposing location but none of them is labeled as default location, then the query will be declared ambiguous and an HTTP error response with a 409 code must be sent.

  • If there is more than one attribute exposing location labeled as default location, then the query is declared ambiguous and an HTTP error response with a 409 code must be sent.

Notification Messages

Notifications include two fields:

  • subscriptionId represents the concerned subscription that originates the notification
  • data is an array with the notification data itself which includes the entity and all concerned attributes. Each element in the array corresponds to a different entity. By default, the entities are represented in normalized mode. However, using the attrsFormat modifier, a simplified representation mode can be requested.

If attrsFormat is normalized (or if attrsFormat is omitted) then default entity representation is used:

{
  "subscriptionId": "12345",
  "data": [
    {
      "id": "Room1",
      "type": "Room",
      "temperature": {
        "value": 23,
        "type": "Number",
        "metadata": {}
      },
      "humidity": {
        "value": 70,
        "type": "percentage",
        "metadata": {}
      }
    },
    {
      "id": "Room2",
      "type": "Room",
      "temperature": {
        "value": 24,
        "type": "Number",
        "metadata": {}
      }
    }
  ]
}

If attrsFormat is keyValues then keyValues partial entity representation mode is used:

{
  "subscriptionId": "12345",
  "data": [
    {
      "id": "Room1",
      "type": "Room",
      "temperature": 23,
      "humidity": 70
    },
    {
      "id": "Room2",
      "type": "Room",
      "temperature": 24
    }
  ]
}

If attrsFormat is values then values partial entity representation mode is used:

{
  "subscriptionId": "12345",
  "data": [ [23, 70], [24] ]
}

Notifications must include the Ngsiv2-AttrsFormat HTTP header with the value of the format of the associated subscription, so that notification receivers are aware of the format without needing to process the notification payload.

Custom Notifications

NGSIv2 clients can customize HTTP notification messages using a simple template mechanism. The notification.httpCustom property of a subscription allows to specify the following fields to be templatized:

  • url
  • headers (both header name and value can be templatized)
  • qs (both parameter name and value can be templatized)
  • payload

The fifth field method, lets the NGSIv2 clients select the HTTP method to be used for delivering the notification, but note that only valid HTTP verbs can be used: GET, PUT, POST, DELETE, PATCH, HEAD, OPTIONS, TRACE, and CONNECT.

Macro substitution for templates is based on the syntax ${..}. In particular:

  • ${id} is replaced by the id of the entity
  • ${type} is replaced by the type of the entity
  • Any other ${token} is replaced by the value of the attribute whose name is token or with an empty string if the attribute is not included in the notification. If the value is a number, a bool or null then its string representation is used. If the value is a JSON array or object then its JSON representation as string is used.

Example:

Let's consider the following notification.httpCustom object in a given subscription.

"httpCustom": {
  "url": "http://foo.com/entity/${id}",
  "headers": {
    "Content-Type": "text/plain"
  },
  "method": "PUT",
  "qs": {
    "type": "${type}"
  },
  "payload": "The temperature is ${temperature} degrees"
}

Now let's assume that a notification associated to this subscription is triggered, and that the notification data is for an entity with id "DC_S1-D41" and type "Room", and including an attribute named "temperature" with the value 23.4. The resulting notification after applying the template would be:

PUT http://foo.com/entity/DC_S1-D41?type=Room
Content-Type: text/plain
Content-Length: 31

The temperature is 23.4 degrees

Some considerations to take into account:

  • It is the NGSIv2 client's responsability to ensure that after substitution, the notification is a correct HTTP message (e.g. if the Content-Type header is application/xml, then the payload must correspond to a well-formed XML document). Specifically, if the resulting URL after applying the template is malformed, then no notification is sent.
  • In case the data to notify contains more than one entity, a separate notification (HTTP message) is sent for each of the entities (contrary to default behaviour, which is to send all entities in the same HTTP message).

Note that if a custom payload is used for the notification (the field payload is given in the corresponding subscription), then a value of custom is used for the Ngsiv2-AttrsFormat header in the notification.

API Specification

API Entry Point

Retrieve API Resources

[/v2]

Retrieve API Resources

GET /v2

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.

Entities

List entities

[/v2/entities{?attrs,coords,geometry,georel,id,idPattern,limit,offset,options,orderBy,q,type}]

List entities

GET /v2/entities{?attrs,coords,geometry,georel,id,idPattern,limit,offset,options,orderBy,q,type}

Retrieves a list of entities that match different criteria (by id, idPattern, type or those which match a query or geographical query). 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 the id and idPattern parameters are incompatible - cannot be used together. See Simple Query Language and Geographical Queries.

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.

Parameters
attrs (optional, string)

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.

coords (optional, string)

List of latitude-longitude pairs of coordinates separated by ';'. See Geographical Queries.

geometry (optional, string)

Geografical area to which the query is restricted. See Geographical Queries.

georel (optional, string)

Spatial relationship between matching entities and a reference shape. See Geographical Queries.

id (optional, string)

A comma-separated list of elements. Retrieve entities whose ID matches one of the elements in the list. Incompatible with idPattern.

idPattern (optional, string)

A correctly formated regular expression. Retrieve entities whose ID matches the regular expression. Incompatible with id.

limit (optional, number)

Limits the number of entities to be retrieved

offset (optional, number)

Establishes the offset from where entities are retrieved

options (optional, string)

Options dictionary

Allowed values:

count

when used, the total number of entities is returned in the response as an HTTP header named Fiware-Total-Count.

keyValues

when used, the response payload uses the keyValues simplified entity representation. See "Simplified Entity Representation" section for details.

values

when used, the response payload uses the values simplified entity representation. See "Simplified Entity Representation" section for details.

unique

when used, the response payload uses the values simplified entity representation. Recurring values are left out. See "Simplified Entity Representation" section for details.

orderBy (optional, string)

Criteria for ordering results. See "Ordering Results" section for details.

q (optional, string)

A query expression, composed of a list of statements separated by ;, i.e., q=statement;statements;statement. See Simple Query Language specification.

type (optional, string)

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

Create entity

[/v2/entities{?options}]

Create entity

POST /v2/entities{?options}

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. Reponse 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.

Parameters
options (optional, string)

Options dictionary

Allowed values:

keyValues

when used, the request payload uses the keyValues simplified entity representation. See "Simplified Entity Representation" section for details.

Entity by ID

[/v2/entities/{entityId}{?attrs,options,type}]

Retrieve entity

GET /v2/entities/{entityId}{?attrs,options,type}

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.

Parameters
attrs (optional, string)

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. 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.

entityId (required, string)

Id of the entity to be retrieved

options (optional, string)

Options dictionary

Allowed values:

keyValues

when used, the response payload uses the keyValues simplified entity representation. See "Simplified Entity Representation" section for details.

values

when used, the response payload uses the values simplified entity representation. See "Simplified Entity Representation" section for details.

unique

when used, the response payload uses the values simplified entity representation. Recurring values are left out. See "Simplified Entity Representation" section for details.

type (optional, string)

Entity type, to avoid ambiguity in case there are several entities with the same entity id.

Retrieve entity attributes

GET /v2/entities/{entityId}/attrs{?attrs,options,type}

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.

Parameters
attrs (optional, string)

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.

entityId (required, string)

Id of the entity to be retrieved

options (optional, string)

Options dictionary

Allowed values:

keyValues

when used, the response payload uses the keyValues simplified entity representation. See "Simplified Entity Representation" section for details.

values

when used, the response payload uses the values simplified entity representation. See "Simplified Entity Representation" section for details.

unique

when used, the response payload uses the values simplified entity representation. Recurring values are left out. See "Simplified Entity Representation" section for details.

type (optional, string)

Entity type, to avoid ambiguity in the case there are several entities with the same entity id.

Update or append entity attributes

POST /v2/entities/{entityId}/attrs{?options,type}

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.

Parameters
entityId (required, string)

Entity id to be updated

options (optional, string)

Operations options

Allowed values:

append

Force an append operation

keyValues

when used, the request payload uses the keyValues simplified entity representation. See "Simplified Entity Representation" section for details.

type (optional, string)

Entity type, to avoid ambiguity in case there are several entities with the same entity id.

Update existing entity attributes

PATCH /v2/entities/{entityId}/attrs{?options,type}

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.

Parameters
entityId (required, string)

Id of the entity to be updated

options (optional, string)

Operations options

Allowed values:

keyValues

when used, the request payload uses the keyValues simplified entity representation. See "Simplified Entity Representation" section for details.

type (optional, string)

Entity type, to avoid ambiguity in case there are several entities with the same entity id.

Replace all entity attributes

PUT /v2/entities/{entityId}/attrs{?options,type}

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.

Parameters
entityId (required, string)

Id of the entity in question.

options (optional, string)

Operations options

Allowed values:

keyValues

when used, the request payload uses the keyValues simplified entity representation. See "Simplified Entity Representation" section for details.

type (optional, string)

Entity type, to avoid ambiguity in the case there are several entities with the same entity id.

Remove entity

DELETE /v2/entities/{entityId}{?type}

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.

Parameters
entityId (required, string)

Id of the entity to be deleted

type (optional, string)

Entity type, to avoid ambiguity in the case there are several entities with the same entity id.

Attributes

Attribute by Entity ID

[/v2/entities/{entityId}/attrs/{attrName}{?type}]

Get attribute data

GET /v2/entities/{entityId}/attrs/{attrName}{?type}

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 20O OK.

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

Parameters
attrName (required, string)

Name of the attribute to be retrieved.

entityId (required, string)

Id of the entity

type (optional, string)

Entity type, to avoid ambiguity in the case there are several entities with the same entity id.

Update attribute data

PUT /v2/entities/{entityId}/attrs/{attrName}{?type}

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.

Parameters
attrName (required, string)

Attribute name

entityId (required, string)

Id of the entity to update

type (optional, string)

Entity type, to avoid ambiguity in case there are several entities with the same entity id.

Remove a single attribute

DELETE /v2/entities/{entityId}/attrs/{attrName}{?type}

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.

Parameters
attrName (required, string)

Attribute name.

entityId (required, string)

Id of the entity.

type (optional, string)

Entity type, to avoid ambiguity in the case there are several entities with the same entity id.

Attribute Value

By Entity ID

[/v2/entities/{entityId}/attrs/{attrName}/value?{type}]

Get attribute value

GET /v2/entities/{entityId}/attrs/{attrName}/value{?type}

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 the 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 20O OK.

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

Parameters
attrName (required, string)

Name of the attribute to be retrieved.

entityId (required, string)

Id of the entity in question

type (optional, string)

Entity type, to avoid ambiguity in the case there are several entities with the same entity id.

Update attribute value

PUT /v2/entities/{entityId}/attrs/{attrName}/value{?type}

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.

Parameters
attrName (required, string)

Attribute name.

entityId (required, string)

Id of the entity to be updated.

type (optional, string)

Entity type, to avoid ambiguity in the case there are several entities with the same entity id.

Types

Entity types

[/v2/types{?limit,offset,options}]

Retrieve entity types

GET /v2/types/{?limit,offset,options}

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.

Parameters
limit (optional, number)

Limit the number of types to be retrieved.

offset (optional, number)

Skip a number of records.

options (optional, string)

Options dictionary.

Allowed values:

count

when used, the total number of types is returned in the HTTP header Fiware-Total-Count

values

when used, the response payload is a JSON array with a list of entity types

Entity type

[/v2/types/{entityType}]

Retrieve entity type

GET /v2/types/{entityType}

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.

Parameters
entityType (required, string)

Entity Type

Subscriptions

A subscription is represented by a JSON object with the following fields:

  • id: Subscription unique identifier. Automatically created at creation time.

  • description (optional): A free text used by the client to describe the subscription.

  • subject: An object that describes the subject of the subscription.

  • notification: An object that describes the notification to send when the subscription is triggered.

  • expires: Subscription expiration date in ISO8601 format. Permanent subscriptions must omit this field.

  • status: Either active (for active subscriptions) or inactive (for inactive subscriptions). If this field is not provided at subscription creation time, new subscriptions are created with the active status, which can be changed by clients afterwards. For expired subscriptions, this attribute is set to expired (no matter if the client updates it to active/inactive).

  • throttling: Minimal period of time in seconds which must elapse between two consecutive notifications. It is optional.

A subject contains the following subfields:

  • entities: A list of objects, each one composed of the following subfields (id/idPattern or type must be present):

    • id or idPattern: Id or pattern of the affected entities. Both cannot be used at the same time, but at least one of them must be present.
    • type: Type of the affected entities (optional).
  • condition: Condition to trigger notifications. It has two optional properties:

    • attrs: array of attribute names
    • expression: an expression composed of q, georel, geometry and coords (see "List entities" operation above about this field).

A notification object contains the following subfields:

  • attrs or exceptAttrs (both cannot be used at the same time):
  • attrs: List of attributes to be included in notification messages. It also defines the order in which attributes must appear in notifications when attrsFormat value is used (see "Notification Messages" section). An empty list means that all attributes are to be included in notifications.
  • exceptAttrs: List of attributes to be excluded from the notification message, i.e. a notification message includes all entity attributes except the ones listed in this field.
  • If neither attrs nor exceptAttrs is specified, all attributes are included in notifications.

  • http or httpCustom (one of them must be present, but not both at the same time): It is used to convey parameters for notifications delivered through the HTTP protocol.

  • attrsFormat (optional): specifies how the entities are represented in notifications. Accepted values are normalized (default), keyValues or values. If attrsFormat takes any value different than those, an error is raised. See detail in "Notification Messages" section.

  • timesSent (not editable, only present in GET operations): Number of notifications sent due to this subscription.

  • lastNotification (not editable, only present in GET operations): Last notification date in ISO8601 format.

An http object contains the following subfields:

  • url : URL referencing the service to be invoked when a notification is generated. An NGSIv2 compliant server must support the http URL schema. Other schemas could also be supported.

An httpCustom object contains the following subfields.

  • url: same as in http above.

  • headers (optional): a key-map of HTTP headers that are included in notification messages.

  • qs (optional): a key-map of URL query parameters that are included in notification messages.

  • method (optional): the method to use when sending the notification (default is POST). Only valid HTTP methods are allowed. On specifying an invalid HTTP method, a 400 Bad Request error is returned.

  • payload (optional): the payload to be used in notifications. If omitted, the default payload (see "Notification Messages" sections) is used.

If httpCustom is used, then the considerations described in "Custom Notifications" section apply.

Notification rules are as follow:

  • If attrs and expression are used, a notification is sent whenever one of the attributes in the attrs list changes and at the same time expression matches.

  • If attrs is used and expression is not used, a notification is sent whenever any of the attributes in the attrs list changes.

  • If attrs is not used and expression is used, a notification is sent whenever any of the attributes of the entity changes and at the same time expression matches.

  • If neither attrs nor expression are used, a notification is sent whenever any of the attributes of the entity changes.

Subscription List

[/v2/subscriptions]

Retrieve subscriptions

GET /v2/subscriptions{?limit,offset,options}

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.

Parameters
limit (optional, number)

Limit the number of types to be retrieved

offset (optional, number)

Skip a number of records

options (optional, string)

Options dictionary

Allowed values:

count

when used, the total number of subscriptions is returned in the HTTP header Fiware-Total-Count

Create a new subscription

POST /v2/subscriptions

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.

Subscription By ID

[/v2/subscriptions/{subscriptionId}]

Retrieve subscription

GET /v2/subscriptions/{subscriptionId}

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.

Parameters
subscriptionId (required, string)

subscription Id.

Update subscription

PATCH /v2/subscriptions/{subscriptionId}

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.

Parameters
subscriptionId (required, string)

subscription Id.

Delete subscription

DELETE /v2/subscriptions/{subscriptionId}

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.

Parameters
subscriptionId (required, string)

subscription Id.

Batch Operations

Update

[/v2/op/update]

Update

POST /v2/op/update

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, APPEND_STRICT, UPDATE, DELETE.

  • entities, an array of entities, each one specified using the JSON entity representation format (described in the section "JSON Entity Representation").

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.

Parameters
options (optional, string)

Options dictionary

Allowed values:

keyValues

when used, the request payload uses the keyValues simplified entity representation. See the "Simplified Entity Representation" section for details.

Query

[/v2/op/query{?limit,offset,options}]

Query

POST /v2/op/query{?limit,offset,options}

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 entity is represented by a JSON object with the following elements:

    • id or idPattern: Id or pattern of the affected entities. Both cannot be present at the same time, but one of them must be.
    • type: specifies the type of the entities to search for. If omitted, it means "any entity type".
  • attributes: a list of attribute names to search for. If omitted, it means "all attributes".

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.

Parameters
limit (optional, number)

Limit the number of entities to be retrieved.

offset (optional, number)

Skip a number of records.

options (optional, string)

Options dictionary

Allowed values:

count

the total number of entities is returned in the response as an HTTP header named Fiware-Total-Count.

keyValues

when used, the response payload uses the keyValues simplified entity representation. See "Simplified Entity Representation" section for details.

values

when used, the response payload uses the values simplified entity representation. See "Simplified Entity Representation" section for details.

unique

when used, the response payload uses the values simplified entity representation. recurring values are left out. See "Simplified Entity Representation" section for details.

orderBy (optional, string)

Criteria for ordering results. See "Ordering Results" section for details.

Examples

Entities

Create entity

[/v2/entities{?options}]
Create entity
POST /v2/entities{?options}
Request /v2/entities (application/json)

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"
      }
    }
  }
}
Response 201

Headers

Location: /v2/entities/Bcn-Welt?type=Room

Entity by ID

[/v2/entities/{entityId}{?attrs,options,type}]
Update or append entity attributes
POST /v2/entities/{entityId}/attrs{?options,type}
Request /v2/entities/{entityId}/attrs (application/json)

Headers

Content-Type: application/json

Body

{
  "ambientNoise": {
    "value": 31.5
  }
}
Response 204

Update existing entity attributes
PATCH /v2/entities/{entityId}/attrs{?options,type}
Request /v2/entities/{entityId}/attrs (application/json)

Headers

Content-Type: application/json

Body

{
  "temperature": {
    "value": 25.5
  },
  "seatNumber": {
    "value": 6
  }
}
Response 204

Replace all entity attributes
PUT /v2/entities/{entityId}/attrs{?options,type}
Request /v2/entities/{entityId}/attrs (application/json)

Headers

Content-Type: application/json

Body

{
  "temperature": {
    "value": 25.5
  },
  "seatNumber": {
    "value": 6
  }
}
Response 204

Attributes

Attribute by Entity ID

[/v2/entities/{entityId}/attrs/{attrName}{?type}]
Update attribute data
PUT /v2/entities/{entityId}/attrs/{attrName}{?type}
Request /v2/entities/Bcn_Welt/attrs/temperature (application/json)

Headers

Content-Type: application/json

Body

{
  "value": 25.0,
  "metadata": {
    "unitCode": {
      "value": "CEL"
    }
  }
}
Response 200

Attribute Value

By Entity ID

[/v2/entities/{entityId}/attrs/{attrName}/value?{type}]
Update attribute value
PUT /v2/entities/{entityId}/attrs/{attrName}/value{?type}
Request /v2/entities/Bcn_Welt/attrs/temperature/value (application/json)

Headers

Content-Type: application/json

Body

{
  "address": "Ronda de la Comunicacion s/n",
  "zipCode": 28050,
  "city": "Madrid",
  "country": "Spain"
}
Response 200

Subscriptions

Subscription List

[/v2/subscriptions]
Create a new subscription
POST /v2/subscriptions
Request /v2/subscriptions (application/json)

Headers

Content-Type: application/json

Body

{
  "description": "One subscription to rule them all",
  "subject": {
    "entities": [
      {
        "idPattern": ".*",
        "type": "Room"
      }
    ],
    "condition": {
      "attrs": [ "temperature" ],
      "expression": {
        "q": "temperature>40"
      }
    }
  },
  "notification": {
    "http": {
      "url": "http://localhost:1234"
    },
    "attrs": ["temperature", "humidity"]
  },            
  "expires": "2016-04-05T14:00:00.00Z",
  "throttling": 5
}
Response 201

Headers

Location: /v2/subscriptions/abcde98765

Subscription By ID

[/v2/subscriptions/{subscriptionId}]
Update subscription
PATCH /v2/subscriptions/{subscriptionId}
Request /v2/subscriptions/abcdef (application/json)

Headers

Content-Type: application/json

Body

{
  "expires": "2016-04-05T14:00:00.00Z"
}
Response 204

Batch Operations

Update

[/v2/op/update]
Update
POST /v2/op/update
Request /v2/op/update (application/json)

Headers

Content-Type: application/json

Body

{
  "actionType": "APPEND",
  "entities": [
    {
      "type": "Room",
      "id": "Bcn-Welt",
      "temperature": {
        "value": 21.7
       },
      "humidity": {
        "value": 60
      }
    },
    {
      "type": "Room",
      "id": "Mad_Aud",
      "temperature": {
        "value": 22.9
      },
      "humidity": {
        "value": 85
      }
    }
  ]
}
Response 204

Query

[/v2/op/query{?limit,offset,options}]
Query
POST /v2/op/query{?limit,offset,options}
Request /v2/op/query?limit=10&offset=20 (application/json)

Headers

Content-Type: application/json

Body

{
  "entities": [
    {
      "idPattern": ".*",
      "type": "myFooType"
    },
    {
      "id": "myBar",
      "type": "myBarType"
    }
  ],
  "attributes": [
    "temperature",
    "humidity"
  ]
}
Response 200 (application/json)

Headers

Content-Type: application/json

Body

[
  {
    "type": "Room",
    "id": "DC_S1-D41",
    "temperature": {
      "value": 35.6,
      "type": "Number"
    }
  },
  {
    "type": "Room",
    "id": "Boe-Idearium",
    "temperature": {
      "value": 22.5,
      "type": "Number"
    }
  },
  {
    "type": "Car",
    "id": "P-9873-K",
    "speed": {
      "value": 100,
      "type": "number",
      "accuracy": 2,
      "timestamp": {
        "value": "2015-06-04T07:20:27.378Z",
        "type": "DateTime"
      }
    }
  }
]

Acknowledgements

The editors would like to express their gratitude to the following people who actively contributed to this specification: Juan José Hierro (Telefónica I+D), Marcos Reyes (Telefónica I+D), Ken Zangelin (Telefónica I+D), Iván Arias León (Telefónica I+D), Carlos Romero Brox (Telefónica I+D), Antonio José López Navarro (Telefónica I+D), Marc Capdevielle (Orange), Gilles Privat (Orange), Sergio García Gómez (Telefónica I+D), Martin Bauer (NEC).

References