In the context of the Web of Things (WoT), a Binding is a blueprint that gives guidance on how to implement a specific IoT protocol, data format or IoT platform. The WoT Thing Description specification explains the overall mechanism and the WoT Binding Registry provides the formal requirements for any binding to follow. This document is a binding for the Hypertext Transfer Protocol (HTTP), which is one of the most used protocols in the Internet to exchange any kind of data related to Webpages, Web APIs, IoT devices and much more.
More specifically, it defines a set of vocabulary terms that can be used inside a Thing Description document, and associated rules which allow to describe WoT operations using HTTP over the network. Additionally, relevant examples are provided to showcase different vocabulary terms and the associated behavior.
the following is a draft introduction
This document describes how to map the HTTP protocol to the W3C Web of Things. At the current state of the WoT specifications, this document mirrors the vocabulary terms and defaults that are defined in the [[WOT-THING-DESCRIPTION11]] (see Section on Protocol Binding based on HTTP).
The fundamental WoT terminology such as Thing, Consumer, Producer, Thing Description (TD), Partial TD, Thing Model (TM), Interaction Model, Interaction Affordance, IoT Platform, Property, Action, Event, Data Schema, Content Type, Protocol Binding, Servient, Vocabulary, Term, Vocabulary Term, WoT Interface, and WoT Runtime are defined in Section 3 of the WoT Architecture specification [[wot-architecture11]].
Per default, the [[WOT-THING-DESCRIPTION11]] supports the Protocol Binding based on HTTP by including the
HTTP
RDF vocabulary definitions from HTTP Vocabulary in RDF 1.0 [[?HTTP-in-RDF10]]. This vocabulary can
be directly used within TD instances by the use of the prefix htv
, which points to
http://www.w3.org/2011/http#
.
On the other hand, going forward, the new version of Thing Description specification does not include the HTTP vocabulary by default.
Thus, newer TDs need to explicitly include the HTTP vocabulary in the @context
field of the TD.
Examples after the table illustrate how to include the HTTP vocabulary in the TD.
Vocabulary term | Description | Assignment | Type |
---|---|---|---|
htv:methodName |
HTTP method name (Literal). | optional |
string
(one of |
htv:headers |
HTTP headers sent with the message. | optional |
array of htv:MessageHeader
|
htv:fieldName |
Header name (Literal), e.g., "Accept" , "Transfer-Encoding" . |
mandatory within htv:MessageHeader |
string
|
htv:fieldValue |
Header value (Literal). To be used together with htv:fieldName inside a htv:MessageHeader |
optional |
string
|
In the example below, the use of the HTTP vocabulary terms is illustrated.
Note that the HTTP vocabulary is explicitly included in the @context
field of the TD.
Furthermore, the humidity
property shows how to use multiple forms to express different content types, where the Consumer needs to include the right content type in the Accept
header.
{ "@context": ["https://www.w3.org/ns/wot-next/td", {"htv":"http://www.w3.org/2011/http#"} ], "id": "urn:uuid:9cd44eef-0b3f-4566-94b0-1358af3d86bd", "title": "MyLampThing", ... "properties": { "temperature": { "type": "string", "forms": [ { "href": "http://example.com/properties/temperature", "op": "readproperty", "htv:methodName": "GET" } ] }, "humidity": { "type": "string", "forms": [ { "href": "http://example.com/properties/humidity", "op": "readproperty", "htv:methodName": "GET", "contentType": "application/json", "htv:headers": [ { "@type": "htv:RequestHeader", "htv:fieldValue": "application/json", "htv:fieldName": "Accept" } ] }, { "href": "http://example.com/properties/humidity", "op": "readproperty", "htv:methodName": "GET", "contentType": "application/cbor", "htv:headers": [ { "@type": "htv:RequestHeader", "htv:fieldValue": "application/cbor", "htv:fieldName": "Accept" } ] } ] } }, "actions": { "toggle": { "forms": [ { "op": "invokeaction", "href": "https://mylamp.example.com/actions/toggle", "htv:methodName": "POST" } ] } }, "events": { "error": { "data": { "type": "string" }, "forms": [ { "op": "subscribeevent", "href": "https://mylamp.example.com/events/error", "subprotocol": "longpoll" } ] } } }
To interact with a Thing that implements the Protocol Binding based on HTTP, a Consumer
needs to know what HTTP method to use when performing a WoT operation. In the general case, a Thing Description can
explicitly include a term indicating the method, i.e.,
htv:methodName
. For the sake of conciseness, the HTTP Protocol Binding defines
Default Values for the operation types listed below, which also aims at convergence of the methods
expected by Things (e.g., GET to read, PUT to write).
As required by the [[WOT-THING-DESCRIPTION11]], when the terms are not present in a form of a TD Affordance containing an HTTP URI Scheme, the defaults in the following table apply.
op value |
Default Binding |
---|---|
readproperty |
"htv:methodName": "GET" |
writeproperty |
"htv:methodName": "PUT" |
invokeaction |
"htv:methodName": "POST" |
readallproperties |
"htv:methodName": "GET" |
writeallproperties |
"htv:methodName": "PUT" |
readmultipleproperties |
"htv:methodName": "GET" |
writemultipleproperties |
"htv:methodName": "PUT" |
The following Thing Description shows the insertion of default values for the values of htv:methodName
based on the table above:
As required by the [[WOT-THING-DESCRIPTION11]], when there multiple op
values, the form is extended by the Consumer.
The following TD example shows how a single form can be extended to two forms to explicitly include the htv:methodName
values.
This section illustrates example sequences of application and protocol transactions that correspond to operations (defined in the Thing Description Specification) implementing various interactions among WoT Consumer and WoT Things. The illustrations show both the concrete protocol transactions and the interactions between the applications running inside the WoT Consumer and WoT Thing and the Consumed Thing and Exposed Thing abstractions.
For the sake of simplicity, remote and local proxies between the Consumer and the Thing are omitted from the following sequences. We also assume HTTP as the concrete protocol and omit any additional transactions for implementing security, such as those that would be used for authentication or to set up a secure connection for HTTPS. Other concrete protocols and the addition of security transactions however would only affect the concrete protocol transactions, not the application-level interactions with the Consumed Thing and Exposed Thing abstractions.
The following sequence illustrates application and network
transactions to implement the
readproperty
operation
with an HTTP protocol binding.
The following sequence illustrates application and network
transactions to implement the
writeproperty
operation
with an HTTP protocol binding.
The following sequence illustrates application and network
transactions to implement the
observeproperty
operation
with an HTTP protocol binding using
the "longpolling" (Long Polling) subprotocol.
The following sequence illustrates application and network
transactions to implement the observeproperty
operation
with an HTTP protocol binding using
the "sse" (Server Sent Event) subprotocol.
The following sequence illustrates application and network
transactions to implement the observeproperty
operation
with an HTTP protocol binding using
a WebSocket-based subprotocol.
The following sequence illustrates application and network
transactions to implement the
invokeaction
operation
with an HTTP protocol binding, where the
operation is synchronous and the response from the server
is delayed until after the action completes.
In the following, note that there is no explicit operation defined for event notification itself.
The subprotocol used for notification is associated with
the subscribeevent
operation, and any necessary concrete
protocol transactions are managed by the Protocol Binding subsystem.
There are also several subprotocols possible for event notification using WebSockets. The interaction diagrams show only one of several possible implementations.
The following sequence illustrates application and network
transactions to implement the
subscribeevent
and unsubscribeevent
operations
with an HTTP protocol binding using the Long Polling subprotocol.
The following sequence illustrates application and network
transactions to implement the
subscribeevent
and unsubscribeevent
operations
with an HTTP protocol binding using the Server Sent Event subprotocol.
The following sequence illustrates application and network
transactions to implement the subscribeevent
and unsubscribeevent
operations
with an HTTP protocol binding using a WebSocket subprotocol.