OGC IoT RESTful API

1. Introduction

Since the OGC IoT RESTful API is based on REST principles, it's very easy to write and test applications. You can use your browser to access URLs, and you can use pretty much any HTTP client in any programming language to interact with the API.

In order to provide a unified access to IoT devices' data and tasking capabilities, the OGC IoT RESTful APi defines an IoT data model. The core of the IoT data model is a Thing [1]. Every Thing can have zero to many locations in space and time. each Thing can have zero to many Datastreams, and Datastream forms the core of the Sensing Profile. The IoT data model consists of two parts: (1) the Sensing Profile and (2) the Tasking Profile. The Sensing Profile allowing IoT devices and applications to CREATE, READ, UPDATE, and DELETE (i.e., HTTP POST, GET, PUT, and DELETE) IoT data from sensors. The Tasking Profile allowing applications to control IoT devices.

Sensing

In the Sensing Profile, a Thing has a Location in space and time. A Thing also can have multiple Datastreams. A Datastreams is a collection of Observations. An Observation is an event performed by a Sensor at a location and a time that produces a result whose value is an estimate of an Observed Property of the Feature of Interest

Tasking

In the Tasking Profile, a Thing can have multiple Tasking Capabilities as executable function, which is executed by an Actuator. Users can create task entities in the service to execute Tasks.

The following figure shows the OGC IoT RESTful data model. The properties of entity type and each entity's direct relation to the other entity types are described after the figure.

Figure 1. The OGC IoT RESTful API Data Model

2. Sensing Profile

The sensing profile includes thing, location, datastream, sensor, observedProperty, observation, and feature of interest entity types. In this section, we explain the properties in each entity type and the direct relation to the other entity types. In addition, for each entity type, we show an example of its JSON encoding.

Each entity has some common properties including a unique identifier, a self link showing the URL of the entity, and one-to-many navigation links representing the relation with the other entities.

Common Properties:

Name	Definition	Data type	Multiplicity and use
ID	ID is the system-generated identifier of an entity. ID is unique among the entities of the same entity type.	Any	One (mandatory)
Self-Link	Self-Link is the absolute URL of an entity which is unique among all other entities.	URL	One (mandatory)
Navigation-Link	Navigation-Link is the relative URL showing the relationship with the entities in other entity types.	URL	Zero-to-many

2.1 Thing

Definition: We use the ITU-T definition, i.e., with regard to the Internet of Things, a thing is an object of the physical world (physical things) or the information world (virtual things) which is capable of being identified and integrated into communication networks. (ITU-T Y.2060)

Properties:

Name	Definition	Data type	Multiplicity and use
Description	This is the description of the thing entity. The content is open to accommodate changes to SensorML and to support other description languages.	Character String	One (mandatory)

Direct relation with other entity types:

Entity type	Relation	Description
Location	Many mandatory to many optional	A thing can locate at different geographical positions at different time points (multiple locations). Multiple things can locate at the same location at the same time. A thing may not have a location.
Datastream	One mandatory to many optional	A thing can have zero-to-many datastreams. A datastream entity can only link to a thing as a collection of observations or properties.
TaskingCapability	One mandatory to many optional	A thing can have zero-to-many taskingcapabilities. A taskingcapability entity can only link to a thing as a function of the thing.

Example:

{
						"Description": "thing_1",
						"Self-Link": "http://demo.student.geocens.ca:8080/SWIOT_V2.01/Things(1)",
						"Locations":
						{
							"Navigation-Link": "Things(1)/Locations"
						},
						"ID": 1,
						"Datastreams":
						{
							"Navigation-Link": "Things(1)/Datastreams"
						},
						"TaskingCapabilities":
						{
							"Navigation-Link": "Things(1)/TaskingCapabilities"
						}
					}

2.2 Location

Definition: A location is an absolute geographical position at a specific time point.

Properties:

Name	Definition	Data type	Multiplicity and use
Time	The time point/period of the location.	ISO8601 time point/period string	One (mandatory)
Geometry	The absolute geographical position of the location. This is generally the GeoJSON geometry object.	GeoJSON geometry object	One (mandatory)

Direct relation with other entity types:

Entity type	Relation	Description
Thing	Many optional to many mandatory	A thing can locate at different geographical positions at different time points (multiple locations). Multiple things can locate at the same location at the same time. A thing may not have a location.

Example:

{
						"Things":
						{
							"Navigation-Link": "Locations(1)/Things"
						},
						"Time": "2012-11-17T06:33:19-0700",
						"Self-Link": "http://demo.student.geocens.ca:8080/SWIOT_V2.01/Locations(1)",
						"ID": 1,
						"Geometry":
						{
							"type": "POINT",
							"coordinates":
							[
							100,
							50
							]
						}
					}

2.3 Datastream

Definition: A datastream serves as a collection of observations or properties of a thing. The observations of a datastream are performed by at most one sensor measuring one observed property (i.e., one phenomenon).

Properties:

Name	Definition	Data type	Multiplicity and use
Description	This is the description of the datastream entity. The content is open to support other description languages.	Character String	One (mandatory)

Direct relation with other entity types:

Entity type	Relation	Description
Thing	Many optional to one mandatory	A thing can have zero-to-many datastreams. A datastream entity can only link to a thing as a collection of observations or properties.
Sensor	One mandatory to one optional	The observations of a datastream are performed by the same sensor. In some scenarios that sensors are hard to be identified (e.g., observations represent a property of a thing), this data model allows data providers to omit the sensors.
ObservedProperty	Many mandatory to one mandatory	The observations of a datastream observe the same observedProperty. The observations of different datastreams could observe the same observedProperty.
Observation	One mandatory to many optional	A datastream can have zero-to-many observations. One observation must occur in one and only one datastream.

Example:

{
						"Thing":
						{
							"Navigation-Link": "Datastreams(1)/Thing"
						},
						"Description": "datastream_1",
						"Self-Link": "http://demo.student.geocens.ca:8080/SWIOT_V2.01/Datastreams(1)",
						"Sensor":
						{
							"Navigation-Link": "Datastreams(1)/Sensor"
						},
						"ObservedProperty":
						{
							"Navigation-Link": "Datastreams(1)/ObservedProperty"
						},
						"ID": 1,
						"Observations":
						{
							"Navigation-Link": "Datastreams(1)/Observations"
						}
					}

2.4 Sensor

Definition: A sensor is an instrument that can observe a property or phenomenon with the goal of producing an estimate of the value of the property. In some cases, the sensor in this data model can also be seen as the procedure (method, algorithm, or instrument) defined in OGC 07-022r1.

Properties:

Name	Definition	Data type	Multiplicity and use
Metadata	The detailed description of the sensor or system. The content is open to accommodate changes to SensorML or to support other description languages.	Character String	One (mandatory)

Direct relation with other entity types:

Entity type	Relation	Description
Datastream	One optional to one	The observations of a datastream are performed by the same sensor. In some scenarios that sensors are hard to be identified (e.g., observations represent a property of a thing), this data model allows data providers to omit the sensors.

Example:

{
						"Self-Link": "http://demo.student.geocens.ca:8080/SWIOT_V2.01/Sensors(1)",
						"Datastream":
						{
							"Navigation-Link": "Sensors(1)/Datastream"
						},
						"ID": 1,
						"Metadata": "sensor_1"
					}

2.5 ObservedProperty

Definition: An observedProperty specifies the phenomenon of an observation.

Properties:

Name	Definition	Data type	Multiplicity and use
URN	The URN of the observedProperty/phenomenon.	URN	One (mandatory)
UnitOfMeasurement	The unit of measurement for the observations measuring this observedProperty.	Character String	One (mandatory)

Direct relation with other entity types:

Entity type	Relation	Description
Datastream	One mandatory to many mandatory	The observations of a datastream observe the same observedProperty. The observations of different datastreams could observe the same observedProperty.

Example:

{
						"UnitOfMeasurement": "m/s",
						"Self-Link": "http://demo.student.geocens.ca:8080/SWIOT_V2.01/ObservedProperties(1)",
						"ID": 1,
						"Datastreams":
						{
							"Navigation-Link": "ObservedProperties(1)/Datastreams"
						},
						"URN": "urn:ogc:def:phenomenon:OGC:1.0.30:windspeed"
					}

2.6 Observation

Definition: An act of observing a property or phenomenon on a feature of interest, with the goal of producing an estimate of the value of the property. A specialized event whose result is a data value. [OGC 07-022r1]

Properties:

Name	Definition	Data type	Multiplicity and use
Time	The time point/period of when the observation happens.	ISO8601 time point/period string	One (mandatory)
ResultType	The data type of the ResultValue.	O&M Result Type	One (mandatory)
ResultValue	The estimated value of an observedProperty from the observation.	Any (depends on the ResultType)	One (mandatory)

Direct relation with other entity types:

Entity type	Relation	Description
Datastream	Many optional to one mandatory	A datastream can have zero-to-many observations. One observation must occur in one and only one datastream.
FeatureOfInterest	Many mandatory to one mandatory	An observation observes on one and only one feature of interest. One feature of interest could be observed by one-to-many observations.

Example:

{
						"ResultValue": "69.37143083209186",
						"Time": "2012-10-05T07:35:13-0600",
						"Self-Link": "http://demo.student.geocens.ca:8080/SWIOT_V2.01/Observations(1)",
						"FeatureOfInterest":
						{
							"Navigation-Link": "Observations(1)/FeatureOfInterest"
						},
						"Datastream":
						{
							"Navigation-Link": "Observations(1)/Datastream"
						},
						"ID": 1,
						"ResultType": "Measure"
					}

2.7 FeatureOfInterest

Definition: Features or feature collections that represent the identifiable object(s) on which the sensor systems are making observations. In the case of an in-situ sensor or observations being attributes of the thing, the feature of interest could be the thing itself. For remote sensors, this may be the geographical area or volume that is being sensed.

Properties:

Name	Definition	Data type	Multiplicity and use
Description	This is the description of the feature of interest entity. The content is open to accommodate changes to SensorML and to support other description languages. In the case of the thing itself being the feature of interest, this description property is inherited from the thing entity.	Character String	One (mandatory)
Geometry	The absolute geographical position of the feature of interest. This is generally the GeoJSON geometry object. In the case of the thing itself being the feature of interest, this geometry property is inherited from the thing entity by interpolating the geometries in the location entities.	GeoJSON geometry object	One (mandatory)

Direct relation with other entity types:

Entity type	Relation	Description
Observation	One mandatory to many mandatory	An observation observes on one and only one feature of interest. One feature of interest could be observed by one-to-many observations.

Example:

{
						"Description": "FOI_1",
						"Self-Link": "http://demo.student.geocens.ca:8080/SWIOT_V2.01/FeaturesOfInterest(1)",
						"ID": 1,
						"Observations":
						{
							"Navigation-Link": "FeaturesOfInterest(1)/Observations"
						},
						"Geometry":
						{
							"type": "POLYGON",
							"coordinates": [
							[
							[ 100, 0 ],
							[ 101, 0 ],
							[ 101, 1 ],
							[ 100, 1 ],
							[ 100, 0 ]
							],
							[
							[ 100.2, 0.2 ],
							[ 100.8, 0.2 ],
							[ 100.8, 0.8 ],
							[ 100.2, 0.8 ],
							[ 100.2, 0.2 ]
							]
							]}
						}

3. Tasking Profile

The IoT RESTful taskingCapability profile is mainly for users to control actuators through a unified web service interface. There are two major parts in the taskingCapability profile. The first part is to convey the acceptable parameters of an actuator and allow users to submit controlling tasks through a RESTful interface. The second part of the taskingCapability profile is to allow IoT RESTful services to communicate with actuators that are attached to things.

3.1 TaskingCapability

Definition: A taskingCapability serves as an executable function of a thing. A taskingCapability could be enabled by an actuator.

Properties:

Name	Definition	Data type	Multiplicity and use
Parameter	A taskingCapability may have zero-to-many acceptable parameters. Users can understand the acceptable input of the taskingCapability. An acceptable parameter contains a ParameterID, Description, Use, and Definition (which has UnitOfMeasurement, InputType, and AllowedValues).	Parameter	Zero-to-many
Protocol	The protocol is not visible to users but needs to be registered into service when creating the taskingCapability. The protocol describes the communication protocol of sending tasks to the taskingCapability. The protocol generally is a HTTP Protocol, which contains a HTTP Method, AbsoluteResourcePath, QueryString, Fragment, MessageBody, and Headers (key-value pairs).	HTTP Protocol	One (mandatory)

Direct relation with other entity types:

Entity type	Relation	Description
Thing	Many optional to one mandatory	A thing can have zero-to-many taskingCapabilities. A taskingCapability entity can only link to a thing as a function of that thing.
Actuator	One mandatory to one optional	The tasks of a taskingCapability are performed by the same actuator. In some scenarios that actuators are hard to be identified (e.g., changing a status of a thing), this data model allows data providers to omit the actuators.
Task	One mandatory to many optional	A taskingCapability can have zero-to-many tasks. A task must link to one and only one taskingCapability.

Example:

{
							"Thing":
							{
								"Navigation-Link": "TaskingCapabilities(1)/Thing"
							},
							"Parameters": [
							{
								"ParameterID": "parameter_1",
								"Description": "This is the description1.",
								"Use": "optional",
								"Definition":
								{
									"UnitOfMeasurement": "uom_2",
									"AllowedValues": [
									{
										"Value": 1.2
									},
									{
										"Value": 10.5
									},
									{
										"Max": 32.4,
										"Min": -145.7
									}],
									"InputType": "Double"
								}
							},
							{
								"ParameterID": "parameter_2",
								"Description": "This is the description2.",
								"Use": "mandatory",
								"Definition":
								{
									"UnitOfMeasurement": "uom_1",
									"AllowedValues": [
									{
										"Value": 1
									},
									{
										"Value": 10
									}],
									"InputType": "Integer"
								}
							}],
							"Actuator":
							{
								"Navigation-Link": "TaskingCapabilities(1)/Actuators"
							},
							"Self-Link": "http://demo.student.geocens.ca:8080/SWIOT_V2.01/TaskingCapabilities(1)",
							"ID": 1,
							"Tasks":
							{
								"Navigation-Link": "TaskingCapabilities(1)/Tasks"
							}
						}

3.2 Actuator

Definition: An actuator is an instrument that can execute a task.

Properties:

Name	Definition	Data type	Multiplicity and use
Metadata	The detailed description of the actuator. The content is open to accommodate changes to SensorML or to support other description languages.	Character String	One (mandatory)

Direct relation with other entity types:

Entity type	Relation	Description
TaskingCapability	One optional to one	The tasks of a taskingCapability are executed by the same actuator. In some scenarios that actuators are hard to be identified (e.g., changing a status of a thing), this data model allows data providers to omit the actuators.

Example:

{
							"Self-Link": "http://demo.student.geocens.ca:8080/SWIOT_V2.01/Actuators(1)",
							"TaskingCapability":
							{
								"Navigation-Link": "Actuators(1)/TaskingCapability"
							},
							"ID": 1,
							"Metadata": "actuator_1"
						}

3.3 Task

Definition: A task is a user-submitted request for executing a taskingCapability. A user can specify input values of a task based on the parameters description of a taskingCapability. A user can also specify the time that he/she wants the task to be sent to the thing.

Properties:

Name	Definition	Data type	Multiplicity and use
Time	The time point of when the task to be sent to the thing.	ISO8601 time point string	One (mandatory)
Input	A task may contain zero-to-many inputs for the taskingCapability. An input has a ParameterID (which must match the ParameterID in a parameter of the taskingCapability) and an input value for that ParameterID.	Input	Zero-to-many
Status	The status property of a task is a service-controlled property and cannot be updated by users. IoT RESTful service updates the status based on responses from the thing.	Character String	One (mandatory)

Direct relation with other entity types:

Entity type	Relation	Description
TaskingCapability	Many optional to one mandatory	A taskingCapability can have zero-to-many tasks. A task must link to one and only one taskingCapability.

Example:

{
							"Status": "done",
							"Time": "2012-12-27T20:28:07-0700",
							"Self-Link": "http://demo.student.geocens.ca:8080/SWIOT_V2.01/Tasks(1)",
							"TaskingCapability":
							{
								"Navigation-Link": "Tasks(1)/TaskingCapability"
							},
							"ID": 1,
							"Inputs": [
							{
								"ParameterID": "parameterID_1",
								"Value": 1
							},
							{
								"ParameterID": "parameterID_2",
								"Value": 1.2
							},
							{
								"ParameterID": "parameterID_3",
								"Value": "on"
							}]
						}

4. $capabilities

Similar to some other OGC web service (OWS), the IoT RESTful API has a capabilities document describing the metadata of the service. The OGC IoT RESTful capabilities document is a JSON encoded document. The service should use the capabilities document to advertise the supported functions and any constraints on using these functions. The service may also include the capabilities document to showcase the spatio-temporal coverage of the content. Finally, if the service provides any custom operations, the explanation of those operations should be included in the capabilities document as well.

Figure 2. Capabilities Response

Some portions of the capabilities document are already defined in the OWS Common specification, including the version, ServiceIdentification, and ServiceProvider. Also, the boundedBy and TimePeriod are from the OGC GML specification. The following subsections explain the elements that are specific for the IoT RESTful service; namely the FunctionsMetadata and the CustomOperations.

4.1 FunctionsMetadata

The FunctionsMetadata is used to indicate the supported functions and any possible constraints. In short, the service providers can specify the Service-Level-Agreement (SLA) in the FunctionsMetadata. The functions can be the CRUD and query options; and the constraints can be allowed operators for a function or the service-driven pagination. The FunctionsMetadata section should only contain the functions supported by the service.

Figure 3. FunctionsMetadata Element

In order to unify the Functions and provide examples, any Functions included in the capabilities document must be from the following table, in which the function names are explained in the API reference. On the other hand, for the Constraints, as service providers are allowed to create their own constraints, the following table still lists some defined ConstraintNames to unify the syntax.

FunctionName	ConstraintNames
Create	-
Read	Pagination
Update	-
Delete	-
$orderby	-
$top	-
$skip	-
$filter	Logical operators, Arithmetic operators, Grouping operators, String functions, Date functions, Math functions, Type functions, Geospatial functions
$expand	-
$select	-
$count	-
BatchProcessing	-

4.2 CustomOperations

If the service provides any customized operations, the explanation of those operations should be included in the CustomOperations section. The CustomOperations section lists all the customized operations supported by the service and introduces the protocol of these operations. In the Operation element, the service needs to include the OperationName, HTTPMethod, ReturnType, and any acceptable Parameters.

With the information in the Operation element, users can first compose a request URI by appending the OperationName to the service root URI. Then, if the HTTPMethod is HTTP GET, the ParameterNames and input values should be specified as key-value pairs in the query string after the question symbol �?�. Otherwise, the ParameterNames and input values should be put in the message body of the request.

Figure 4. Operation Element