API Reference

2.1 Resource Path

The resource path comes right after the service root URI and can be used to address to different resources. The following lists the general usages of the resource path.

Usage 1: No resource path

If a user request does not include any resource path, the IoT RESTful service returns a list of collection names as the service document.

URI Pattern: SERVICE_ROOT_URI

Response: A list of collection names.

Example: http://demo.student.geocens.ca:8080/SWIOT_V0.9/

Usage 2: Address to an entity collection

To address to an entity collection, users can simply put the collection name after the service root URI. The service returns a list of all the entities in the specified collection.

URI Pattern: SERVICE_ROOT_URI/COLLECTION_NAME

Response: A list of all entities (with all the properties) in the specified collection (if no service-driven pagination imposed).

Example: http://demo.student.geocens.ca:8080/SWIOT_V0.9/Things

Usage 3: Address to an entity in a collection

Users can address to a specific entity in a collection by place the unique identifier of the entity between brace symbol “()” and put after the collection name. The service then returns the entity with all its properties.

URI Pattern: SERVICE_ROOT_URI/COLLECTION_NAME(KEY_OF_ENTITY)

Response: An entity (with all its properties) that holds the specified key in the collection.

Example: http://demo.student.geocens.ca:8080/SWIOT_V0.9/Things(1)

Usage 4: Address to a property of an entity

Users can address to a property of an entity by specifying the property name after the URI addressing to the entity. The service then returns the value of the specified property.

URI Pattern: SERVICE_ROOT_URI/COLLECTION_NAME(KEY_OF_ENTITY)/PROPERTY_NAME

Response: The specified property of an entity that holds the key in the collection.

Example: http://demo.student.geocens.ca:8080/SWIOT_V0.9/Observations(1)/Time

Usage 5: Address to a navigation property (link)

As the entities in different collections may hold some relationships, users can request the linked entities by addressing to a navigation property of an entity. The service then returns one or many entities that hold a certain relationship with the specified entity.

URI Pattern: SERVICE_ROOT_URI/COLLECTION_NAME(KEY_OF_ENTITY)/LINK_NAME

Response: One or many entities that holds a certain relationship with the specified entity.

Example: http://demo.student.geocens.ca:8080/SWIOT_V0.9/Datastreams(1)/Observations returns all the observations in the datastream.

Usage 6: Nested resource path

As users can use navigation properties to link from one collection to another, users can further extend the resource path with unique identifiers, properties, or links (i.e., Usage 3 to 5).

Example 1: http://demo.student.geocens.ca:8080/SWIOT_V0.9/Datastreams(1)/Observations(1) returns a specific observation in the datastream.

Example 2: http://demo.student.geocens.ca:8080/SWIOT_V0.9/Datastreams(1)/Observations(1)/Time turns the “Time” property of the specified observation in the datastream.

Example 3: http://demo.student.geocens.ca:8080/SWIOT_V0.9/Datastreams(1)/Observations(1)/FeatureOfInterest returns the feature of interest entity of the specified observation in the datastream.

2.2 Query Options

When users perform the READ action on resource(s), users can apply query options to further process the addressed resources. As the read action is performed through HTTP GET method, the query options are specified as key-value pairs after the question symbol "?" in the request URI. Currently, many of the query options defined in the OGC IoT RESTful API are similar to the query options in the OData. Therefore, some of the following explanations can be referenced to the OData specification.

NOTE: As our reference implementation hasn't supported all the functions proposed here, we use some examples from the OData test service (http://services.odata.org) to illustrate these functions. As OData might change their demo service, you might find some of the following OData examples not working. And some of the functions, there are no examples available, and these examples uses a pseudo-service root URL (e.g., http://example.com/)

2.2.1 $orderby

The $orderby query option is used to specify which properties are used to order the collection of entities identified by the resource path. This query option is only supported when the resource path identifies a collection of entries. The value of the $orderby query option contains a comma separated list of expressions whose primitive result values are used to sort the results. A special case of such an expression is a property path terminating on a primitive property.

The expression may include the suffix asc for ascending or desc for descending, separated from the property name by one or more spaces. If asc or desc is not specified, the service must order by the specified property in ascending order.

Null values come before non-null values when sorting in ascending order and after non-null values when sorting in descending order.

Example 1: http://services.odata.org/V3/OData/OData.svc/Products?$orderby=Rating returns all Products ordered by the Rating property in ascending order.

Example 2: http://services.odata.org/V3/OData/OData.svc/Products?$orderby=Rating,Category/Name desc returns all Products ordered by the Rating property in ascending order, then by the Name property of the linked Category entry in descending order.

2.2.2 $top

The $top query option specifies a non-negative integer that limits the number of entities returned within a collection. The service must return the number of available entities up to, but not exceeding, the specified value.

Usually, the $top query option is used with the $orderby query option. However, while no ordering semantics are mandated, to ensure repeatable results, a data service must always use the same semantics to obtain a full ordering across requests.

In addition, if the $top value exceeds the service-driven pagination limitation (i.e., the largest number of entities the service can return in a single response), the $top query option should be discarded and the pagination limitation should be imposed.

Example 1: http://services.odata.org/V3/OData/OData.svc/Products?$top=5 returns only the first five entities in the Products collection.

Example 2: http://services.odata.org/V3/OData/OData.svc/Products?$top=5&$orderby=Name desc returns the first five Product entries returned in descending order when sorted by the Name property.

2.2.3 $skip

The $skip query option specifies that the result must not include the first n entities, where n is a non-negative integer value specified by the $skip query option.

Usually, the $skip query option is used with the $orderby query option. However, while no ordering semantics are mandated, to ensure repeatable results, a data service must always use the same semantics to obtain a full ordering across requests.

Where $top and $skip are used together, the $skip must be applied before the $top, regardless of the order in which they appear in the request.

Example 1: http://services.odata.org/V3/OData/OData.svc/Products?$skip=5 returns Product entities starting with the sixth Product entity in the Products collection.

Example 2: http://services.odata.org/V3/OData/OData.svc/Products?$skip=2&$top=2&$orderby=Rating returns the third and fourth Product entities from the collection of all Product entities when the collection is sorted by the Rating property in ascending order.

2.2.4 $filter

A URI with a $filter query option identifies a subset of the entries from the collection of entries identified by the resource path of the URI. The subset is determined by selecting only the entries that satisfy the predicate expression specified by the $filter. The value of the $filter option is a Boolean expression.

The expression language that is used in $filter operators supports references to properties and literals. The literal values can be strings enclosed in single quotes, numbers and boolean values (true or false) or datetime values represented as datetime‘ISO 8601 time string’.

Example: http://services.odata.org/V3/OData/OData.svc/Products?$filter=Price lt 10.00 returns all Products whose Price is less than 10.00.

In addition, users may use the properties of linked entities in the $filter predicate. The following are examples of the possible uses of the $filter in the data model of the IoT RESTful service.

Example 1: ttp://iot-rest.example.com/Observations?$filter=ObservedProperty/UnitOfMeasurement eq ‘Celsius’ returns all Observations whose UnitOfMeasurement (a property of ObservedProperty) is ‘Celsius’.

Example 2: http://iot-rest.example.com/Things?$filter=Locations/Geometry st_within(POLYGON ((30 10, 10 20, 20 40, 40 40, 30 10))) returns Things whose current or past locations were in the polygon defined in the Well-Known Text (WKT).

Example 3: http://iot-rest.example.com/ Things?$filter=Sensors/Observations/FeatureOfInterest/ID eq ‘FOI_1’ and Sensors/Observations/Time ge datetime‘2010-06-01T00:00:00Z’ and Sensors/Observations/Time le datetime‘2010-07-01T00:00:00Z’ returns Things that made any observations on a feature of interest with a unique identifier equals to “FOI_1” in June 2010.

2.2.4.1 Built-in filter operations

The OGC IoT RESTful API supports a set of built-in filter operations, as described in the following table.

2.2.4.2 Built-in query functions

IoT RESTful API supports a set of built-in functions that can be used within $filter operations. The following table lists the available functions. Most of these query functions are defined in the OData. However, in order to support more geospatial query functions, IoT RESTful API defines nine additional geospatial functions based on the spatial relationship between two geometry objects defined in the OGC Simple Feature Access specification (part 1, clause 6.1.2.3). The names of these nine functions start with a prefix “st_” as they are named in the OGC Simple Feature Access specification. In addition, for these eight functions, we define that users must specify input geometry in the Well-Known Text (WKT) format.

2.2.5 $expand

The $expand system query option indicates the related entities that must be represented inline. The value of the $expand query option must be a comma separated list of navigation property names. Additionally each navigation property can be followed by a forward slash and another navigation property to enable identifying a multi-level relationship.

Example 1: http://services.odata.org/V3/OData/OData.svc/Categories?$expand=Products returns the collection of Categories as well as each of the Products associated with each Category entity.

Example 2: http://services.odata.org/V3/OData/OData.svc/Categories?$expand=Products/Suppliers returns the collection of Categories, the Products associated with each Category, and the Suppliers associated with each Product.

Example 3: http://services.odata.org/V3/OData/OData.svc/Products?$expand=Category,Suppliers returns the collection of Products as well as the Category and Suppliers associated with each Product.

2.2.6 $select

A data service URI with a $select query option identifies the same set of entries as a URI without a $select query option; however, the value of $select specifies that a response from an IoT RESTful service should return a subset of the properties. The value of a $select query option is a comma-separated list of selection clauses. Each selection clause may be a property name (including navigation property names).

Example 1: http://services.odata.org/V3/OData/OData.svc/Products?$select=Price,Name returns only the Price and Name properties for each Product entity.

Example 2: http://service.odata.org/Categories?$select=Name,Products&$expand=Products/Supplier returns the Name properties of the Category entries, and all the properties of the entries identified by the Products and Suppliers navigation properties.

2.2.7 $count

The $count query option with a value of “true” specifies that the total count of entities within a collection matching the request must be returned along with the result. The $count system query option ignores any $top, $skip, or $expand query options, and returns the total count of results across all pages including only those results matching any specified $filter.

A $count with a value of “false” (or not specified) hints that the service should not return a count.

Example: http://services.odata.org/V3/OData/OData.svc/Products?$count=true returns, along with the results, the total number of products in the set.

3.1 $capabilities Request

HTTP Method: GET

URI Pattern: SERVICE_ROOT_URI/$capabilities

Example: http://demo.student.geocens.ca:8080/SWIOT_V0.9/$capabilities

3.2 $capabilities Response

The capabilities document is a JSON encoded document. This document provides client with service metadata about a specific service instance. A service should use the capabilities document to advertise the supported functions and any constraints on using these functions. A service may also use the capabilities document to showcase the spatio-temporal coverage of the content. Finally, if a service provides any custom operations, the explanation of those operations should be included in the capabilities document as well.

The detail explanation about the capabilities document can be found in datamodel.html#capabilities.

4.2.1 Request

HTTP Method: POST

URI Pattern: SERVICE_ROOT_URI/COLLECTION_NAME

Header: Content-Type: application/json

Message Body: A single valid entity representation for the specified collection.

Example: Create a Thing entity

POST /SWIOT_V0.9/Things HTTP/1.1
Host: demo.student.geocens.ca:8080
Content-Type: application/json

{
  "Description":"This thing is an oven."
}

POST /SWIOT_V0.9/Observations HTTP/1.1
Host: demo.student.geocens.ca:8080
Content-Type: application/json

{
  "Datastream":{"ID":1},
  "Time":"2013-04-18T16:15:00-0700",
  "ResultValue":"124",
  "ResultType" : "Measure",
  "FeatureOfInterest":{"ID":1}
}

POST /SWIOT_V0.9/Things HTTP1.1
Host: demo.student.geocens.ca:8080
Content-Type: application/json

{
  "Description":"This a Thing with one Datastream and one TaskingCapability",
  "Locations":[
  {
    "Geometry":
    {
      "Type":"POINT" ,
      "Coordinates" :[10,10]
    },
	"Time":"2013-04-18T16:15:00-0700"
  }],
  "TaskingCapabilities":[
  {
    "Description":"this is TaskingCapability 1",
    "Parameters":[
    {
      "ParameterID":"paramOn",
      "Description":"on",
      "Use":"mandatory",
      "Definition":
      {
        "InputType":"Integer",
        "UnitOfMeasurement":"brightness degrees",
        "AllowedValues":[{"Min":"10","Max":"15"}]
      }
    }],
    "Protocols":[
    {
      "HTTPMethod":"POST",
      "AbsoluteResourcePath":"http://path.com",
      "MessageBody":"lamp-id=1&on={paramOn}"
    }],
    "Actuator":
    {
      "Metadata":"This is an actuator"
    }
  }],
  "Datastreams":[
  {
    "Description":"this is datastream one",
    "Observations":[
    {
      "Time":"2013-04-18T16:15:00-0700",
      "ResultValue":"124",
      "ResultType" : "Measure",
      "FeatureOfInterest":
      {
        "Description":"foi_desc",
        "Geometry":{
          "Type":"POLYGON" ,
          "Coordinates": [[[100,50],[10,9],[23,4],[100,50]],[[30,20],[10,4],[4,22],[30,20]]]
        }
      }
    }],
    "ObservedProperty":
    {
      "UnitOfMeasurement":"uom_test",
      "URN":"sample URN"
    },
    "Sensor":
    {
      "Metadata":"This is a sensor"
    }
  }]
}

4.2.2 Response

Upon successfully creating an entity, the service response must contain a Location header that contains the URL of the created entity. Upon successful completion the service must respond with 201 Created. Regarding all the HTTP status code, please refer to the HTTP Status Code section.

4.3.1 Request

HTTP Method: GET

URI Pattern: Refer to the URIComponents section, including resource path and query options

4.3.2 Response

The detail explanation about the encodings of resources in the datastream profile can be found in datamodel.html#DatastreamProfile.

Upon successfully retrieve resources, the service service must respond with 200 OK. Regarding all the HTTP status code, please refer to the HTTP Status Code section.

4.4.1 Request

Services should support HTTP PATCH as the preferred means of updating an entity. HTTP PATCH provides more resiliencies between clients and services by directly modifying only those values specified by the client.

The semantics of PATCH, as defined in [RFC5789], are to merge the content in the request payload with the entity’s current state, applying the update only to those components specified in the request body. Collection properties and primitive properties provided in the payload must replace the value of the corresponding property in the entity or complex type. Missing properties of the containing entity or complex property, including dynamic properties, must not be directly altered.

Services may additionally support HTTP PUT, but should be aware of the potential for data-loss in round-tripping properties that the client may not know about in advance. Services that support HTTP PUT must replace all property values with those specified in the request body. Missing properties must be set to their default values. Missing optional properties must be removed.

Unique identifiers and other non-updatable properties may be omitted from the request. If the request contains a value for an identifier or other non-updatable property, the service must ignore that value when applying the update.

The entity must not contain related entities as inline content. Additional values for properties beyond those specified in the IoT RESTful data model should not be sent in the request body. The service should consider such a request malformed.

HTTP Method: PATCH or PUT

URI Pattern: An URI addressing to a single entity.

Header: Content-Type: application/json

Message Body: A single entity representation including a subset of properties for the specified collection.

Example: Update the Thing with key equals to 1

PATCH /SWIOT_V0.9/Things(1) HTTP1.1
Host: demo.student.geocens.ca:8080
Content-Type: application/json

{
  "Description":"This thing is an oven own by the Toms."
}

4.4.2 Response

On success, the response must be a valid success response. In addition, when the client sends an update request to a valid URL where an entity does not exist, the service must fail the request.

Upon successful completion, the service service must respond with 200 OK or 204 No Content. Regarding all the HTTP status code, please refer to the HTTP Status Code section.

4.5.1 Request

To delete an existing entity, the client sends a HTTP DELETE request to that entity's edit URL. The request body should be empty.

HTTP Method: DELETE

URI Pattern: An URI addressing to a single entity.

Example: Delete the Thing with unique identifier equals to 1

HTTP DELETE http://demo.student.geocens.ca:8080/SWIOT_V0.9/Things(1)

Services must implicitly remove relations to and from an entity when deleting it; clients need not delete the relations explicitly.

Services should implicitly delete related entities if required by the following integrity constraints.

4.5.2 Response

On successful completion of the delete, the response must be 200 OK, 202 Accepted, or 204 No Content and contain an empty body. Regarding all the HTTP status code, please refer to the HTTP Status Code section.

6.1 Request

A batch request is represented as a Multipart MIME v1.0 message [RFC2046], a standard format allowing the representation of multiple parts, each of which may have a different content type, within a single request.

POST OData/OData.svc/$batch HTTP/1.1
Host: services.odata.org
DataServiceVersion: 1.0
MaxDataServiceVersion: 2.0
Content-Type: multipart/mixed; boundary=batch(36522ad7-fc75-4b56-8c71-56071383e77b)

BATCH_REQUEST_BODY

( ) < > @ , ; : / " [ ] ? =

POST OData/OData.svc/$batch HTTP/1.1
Host: services.odata.org
Content-Type: multipart/mixed; boundary=batch(36522ad7-fc75-4b56-8c71-56071383e77b)

--batch_36522ad7-fc75-4b56-8c71-56071383e77b
Content-Type: application/http 
Content-Transfer-Encoding:binary

GET /service/Customers('ALFKI') HTTP/1.1
Host: host

--batch_36522ad7-fc75-4b56-8c71-56071383e77b 
Content-Type: multipart/mixed; boundary=changeset_77162fcd-b8da-41ac-a9f8-9357efbbd621 
Content-Length: ###       

--changeset(77162fcd-b8da-41ac-a9f8-9357efbbd621) 
Content-Type: application/http 
Content-Transfer-Encoding: binary 

POST /service/Customers HTTP/1.1 
Host: host  
Content-Type: application/atom+xml;type=entry 
Content-Length: ### 

 

--changeset(77162fcd-b8da-41ac-a9f8-9357efbbd621) 
Content-Type: application/http 
Content-Transfer-Encoding:binary 

PUT /service/Customers('ALFKI') HTTP/1.1 
Host: host 
Content-Type: application/json 
If-Match: xxxxx 
Content-Length: ### 

 

--changeset(77162fcd-b8da-41ac-a9f8-9357efbbd621)-- 

--batch(36522ad7-fc75-4b56-8c71-56071383e77b) 
Content-Type: application/http 
Content-Transfer-Encoding:binary 

GET service/Products HTTP/1.1 
Host: host 

--batch(36522ad7-fc75-4b56-8c71-56071383e77b)--

6.2 Process a Batch Request

Requests within a batch are evaluated according to the same semantics used when the request appears outside of the context of a batch.

The order of ChangeSets and retrieve requests within a Batch request is significant as it states the order in which the service processes the components of the Batch. The order of requests within a ChangeSet is not significant such that a service may process the requests within a ChangeSet in any order.

All operations in a ChangeSet represent a single change unit so the server must successfully process and apply all the requests in the ChangeSet or else apply none of the requests in the ChangeSet. It is up to the service to define rollback semantics to undo any requests within a ChangeSet that may have been applied before another request in that same ChangeSet failed and thereby honor this all-or-nothing requirement.

If the set of HTTP Request headers of a Batch request are valid (the Content-Type is set to multipart/mixed, etc.) the server returns a 202 Accepted HTTP response code to indicate that the request has been accepted for processing, but that the processing has not yet been completed. The requests within the Batch request body may subsequently fail or be malformed; however, this mechanism enables clients of a Batch implementation to stream the results of a Batch request without having to first wait for all requests to be processed.

If the service receives a Batch request with an invalid set of headers it returns a 4xx response code and no further processing of the batch is performed.

6.3 Response

HTTP/1.1 202 Accepted
DataServiceVersion: 1.0
Content-Length: 1254
Content-Type: multipart/mixed; boundary=batch(36522ad7-fc75-4b56-8c71-56071383e77b)
						

HTTP/1.1 202 Accepted
DataServiceVersion: 1.0
Content-Length: ####
Content-Type: multipart/mixed; boundary=batch(36522ad7-fc75-4b56-8c71-56071383e77b)

--batch(36522ad7-fc75-4b56-8c71-56071383e77b)
Content-Type: application/http
Content-Transfer-Encoding: binary

HTTP/1.1 200 Ok
Content-Type: application/atom+xml;type=entry
Content-Length: ###



--batch(36522ad7-fc75-4b56-8c71-56071383e77b)
Content-Type: multipart/mixed; boundary=changeset(77162fcd-b8da-41ac-a9f8-9357efbbd621)
Content-Length: ###      

--changeset(77162fcd-b8da-41ac-a9f8-9357efbbd621)
Content-Type: application/http
Content-Transfer-Encoding: binary

HTTP/1.1 201 Created
Content-Type: application/atom+xml;type=entry
Location: http://host/service.svc/Customer('POIUY')
Content-Length: ###



--changeset(77162fcd-b8da-41ac-a9f8-9357efbbd621)
Content-Type: application/http
Content-Transfer-Encoding: binary

HTTP/1.1 204 No Content
Host: host

--changeset(77162fcd-b8da-41ac-a9f8-9357efbbd621)--

--batch(36522ad7-fc75-4b56-8c71-56071383e77b)
Content-Type: application/http
Content-Transfer-Encoding: binary

HTTP/1.1 404 Not Found
Content-Type: application/xml
Content-Length: ###


--batch(36522ad7-fc75-4b56-8c71-56071383e77b)--