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.
This specification is licensed under the FIWARE Open Specification License (implicit patent license).
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.
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.
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.
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.
The FIWARE NGSI (Next Generation Service Interface) API defines
The main elements in the NGSI data model are context entities, attributes and metadata, as shown in the figure below.
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 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 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.
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.
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.
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": <...>
}
There are two representation modes that must be supported by implementations. These representation modes allow to generate simplified representations of entities.
{
"id": "R12345",
"type": "Room",
"temperature": 22
}
attrs
URI param
(e.g. attrs=branch,colour,engine
). If attrs
is not used, the order is arbitrary.[ 'Ford', 'black', 78.3 ]
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.
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"
}
}
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.
Fields used as identifiers in the NGSIv2 API follow special rules regarding allowed syntax. These rules apply to:
The rules are:
&
, ?
, /
and #
.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.
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")
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.
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):
400
). The incoming JSON payload cannot be parsed.400
). The incoming request is invalid in this context.404
). The resource (entity, subscription, etc.) referred in the request
has not been found.409
). There are several results that match with the resource
identification
used in the request.411
). Zero/No Content-Length in PUT/POST/PATCH request.413
). Payload is too large.415
). Request content type is not supported.422
). Some piece of information is missing in payload.422
). The implementation does not support the query issued.413
). There are no server resources to fulfill the client request. New error codes may be defined in new iterations of this specification.
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 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:
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.
geo:line
: the attribute value must contain a string array of
valid latitude-longitude pairs. There must be at least two pairs.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. 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"
}
}
A context attribute representing a location encoded using GeoJSON must conform to the following syntax:
geo:json
.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"
}
}
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:
==
. This operator accepts the following types of right-hand side:temperature==40
. For an entity to match, it must contain an attribute
with that exact name (temperature) and value (40).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...
, 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.!=
. This operator accepts the following types of right-hand side: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).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...
, 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.>
. 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).<
. 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).>=
. 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).<=
. 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).~=
. 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 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.
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.
Notifications include two fields:
subscriptionId
represents the concerned subscription that originates the notificationdata
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.
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${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:
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.
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, 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.
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.
List of latitude-longitude pairs of coordinates separated by ';'. See Geographical Queries.
Geografical area to which the query is restricted. See Geographical Queries.
Spatial relationship between matching entities and a reference shape. See Geographical Queries.
A comma-separated list of elements. Retrieve entities whose ID matches one of the elements in the list. Incompatible with idPattern.
A correctly formated regular expression. Retrieve entities whose ID matches the regular expression. Incompatible with id.
Limits the number of entities to be retrieved
Establishes the offset from where entities are retrieved
Options dictionary
Allowed values:
when used, the total number of entities is returned in the response as an HTTP header named Fiware-Total-Count
.
when used, the response payload uses the keyValues
simplified entity representation. See "Simplified Entity Representation" section for details.
when used, the response payload uses the values
simplified entity representation. See "Simplified Entity Representation" section for details.
when used, the response payload uses the values
simplified entity representation.
Recurring values are left out.
See "Simplified Entity Representation" section for details.
Criteria for ordering results. See "Ordering Results" section for details.
A query expression, composed of a list of statements
separated by ;
, i.e., q=statement;statements;statement.
See Simple Query Language specification.
comma-separated list of elements. Retrieve entities whose type matches one of the elements in the list.
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.
Options dictionary
Allowed values:
when used, the request payload uses the keyValues
simplified entity representation. See "Simplified Entity Representation" section for 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.
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.
Id of the entity to be retrieved
Options dictionary
Allowed values:
when used, the response payload uses the keyValues
simplified entity representation. See "Simplified Entity Representation" section for details.
when used, the response payload uses the values
simplified entity representation. See "Simplified Entity Representation" section for details.
when used, the response payload uses the values
simplified entity representation. Recurring values are left out.
See "Simplified Entity Representation" section for details.
Entity type, to avoid ambiguity in case there are several entities with the same entity id.
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.
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.
Id of the entity to be retrieved
Options dictionary
Allowed values:
when used, the response payload uses the keyValues
simplified entity representation. See "Simplified Entity Representation" section for details.
when used, the response payload uses the values
simplified entity representation. See "Simplified Entity Representation" section for details.
when used, the response payload uses the values
simplified entity representation. Recurring values are left out.
See "Simplified Entity Representation" section for details.
Entity type, to avoid ambiguity in the case there are several entities with the same entity id.
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.
Entity id to be updated
Operations options
Allowed values:
Force an append operation
when used, the request payload uses the keyValues
simplified entity representation. See "Simplified Entity Representation" section for details.
Entity type, to avoid ambiguity in case there are several entities with the same entity id.
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.
Id of the entity to be updated
Operations options
Allowed values:
when used, the request payload uses the keyValues
simplified entity representation. See "Simplified Entity Representation" section for details.
Entity type, to avoid ambiguity in case there are several entities with the same entity id.
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.
Id of the entity in question.
Operations options
Allowed values:
when used, the request payload uses the keyValues
simplified entity representation. See "Simplified Entity Representation" section for details.
Entity type, to avoid ambiguity in the case there are several entities with the same entity id.
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.
Id of the entity to be deleted
Entity type, to avoid ambiguity in the case there are several entities with the same entity id.
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.
Name of the attribute to be retrieved.
Id of the entity
Entity type, to avoid ambiguity in the case there are several entities with the same entity id.
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.
Attribute name
Id of the entity to update
Entity type, to avoid ambiguity in case there are several entities with the same entity id.
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.
Attribute name.
Id of the entity.
Entity type, to avoid ambiguity in the case there are several entities with the same entity id.
This operation returns the value
property with the value of the attribute.
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:
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.Response:
Successful operation uses 20O OK.
Errors use a non-2xx and (optionally) an error payload. See subsection on "Error Responses" for more details.
Name of the attribute to be retrieved.
Id of the entity in question
Entity type, to avoid ambiguity in the case there are several entities with the same entity id.
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:
"
), the value is taken as a string
(the citation marks themselves are not considered part of the string)true
or false
, the value is taken as a boolean.null
, the value is taken as null.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.
Attribute name.
Id of the entity to be updated.
Entity type, to avoid ambiguity in the case there are several entities with the same entity id.
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.
Limit the number of types to be retrieved.
Skip a number of records.
Options dictionary.
Allowed values:
when used, the total number of types is returned in the HTTP header Fiware-Total-Count
when used, the response payload is a JSON array with a list of entity types
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.
Entity Type
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 namesexpression
: 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.
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.
Limit the number of types to be retrieved
Skip a number of records
Options dictionary
Allowed values:
when used, the total number of subscriptions is returned in the HTTP header Fiware-Total-Count
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.
subscription Id.
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.
subscription Id.
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.
subscription Id.
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.
Options dictionary
Allowed values:
when used, the request payload uses the keyValues
simplified entity representation. See the "Simplified Entity Representation"
section for 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 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.
Limit the number of entities to be retrieved.
Skip a number of records.
Options dictionary
Allowed values:
the total number of entities is returned in the response as an HTTP header named Fiware-Total-Count
.
when used, the response payload uses the keyValues
simplified entity representation. See "Simplified Entity Representation" section for details.
when used, the response payload uses the values
simplified entity representation. See "Simplified Entity Representation" section for details.
when used, the response payload uses the values
simplified entity representation. recurring values are left out.
See "Simplified Entity Representation" section for details.
Criteria for ordering results. See "Ordering Results" section for details.
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"
}
}
}
}
Headers
Location: /v2/entities/Bcn-Welt?type=Room
Headers
Content-Type: application/json
Body
{
"ambientNoise": {
"value": 31.5
}
}
Headers
Content-Type: application/json
Body
{
"temperature": {
"value": 25.5
},
"seatNumber": {
"value": 6
}
}
Headers
Content-Type: application/json
Body
{
"temperature": {
"value": 25.5
},
"seatNumber": {
"value": 6
}
}
Headers
Content-Type: application/json
Body
{
"value": 25.0,
"metadata": {
"unitCode": {
"value": "CEL"
}
}
}
Headers
Content-Type: application/json
Body
{
"address": "Ronda de la Comunicacion s/n",
"zipCode": 28050,
"city": "Madrid",
"country": "Spain"
}
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
}
Headers
Location: /v2/subscriptions/abcde98765
Headers
Content-Type: application/json
Body
{
"expires": "2016-04-05T14:00:00.00Z"
}
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
}
}
]
}
Headers
Content-Type: application/json
Body
{
"entities": [
{
"idPattern": ".*",
"type": "myFooType"
},
{
"id": "myBar",
"type": "myBarType"
}
],
"attributes": [
"temperature",
"humidity"
]
}
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"
}
}
}
]
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).