Abstract

In the context of the Web of Things (WoT), a Binding Template is a blueprint that gives guidance on how to implement a specific IoT protocol, data format or IoT platform. The Core Binding Templates specification explains the overall mechanism and requirements for any binding to follow. This document gives implementation guidelines regarding 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.

Introduction

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

This document is a work in progress

Terminology

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

HTTP Vocabulary

HTTP Vocabulary Terms

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 usage of the prefix htv, which points to http://www.w3.org/2011/http#. Here, the relevant vocabulary terms are provided for convenience.

Vocabulary term Description Assignment Type
htv:methodName HTTP method name (Literal). optional string

(one of "GET", "PUT", "POST", "DELETE", "PATCH")
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

HTTP Default Vocabulary Terms

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 Protocol Binding based on HTTP 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).

When no method is indicated in a form representing an Protocol Binding based on HTTP, a Default Value MUST be assumed as shown in the following table.

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:

In the case of a form with multiple op values, htv:methodName SHOULD NOT be used. A Consumer will extend the multiple op values to separate forms entries and associates a single operation with the default assumption. The address information (e.g. href) and other metadata are taken over in the extended version. If the form does not use the default values, multiple forms SHOULD be created with an htv:methodName associated to a single op value.

The following TD example shows how a single form can be extended to two forms to explicitly include the htv:methodName values.

Example Sequences of Interaction Affordances

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.

Property Interactions

Read property (HTTP binding)

The following sequence illustrates application and network transactions to implement the readproperty operation with an HTTP protocol binding.

Read property (HTTP binding)

Write property (HTTP binding)

The following sequence illustrates application and network transactions to implement the writeproperty operation with an HTTP protocol binding.

Write property (HTTP binding)

Observe property (HTTP binding with Long Polling subprotocol)

The following sequence illustrates application and network transactions to implement the observeproperty operation with an HTTP protocol binding using the "longpolling" (Long Polling) subprotocol.

Observe property (HTTP binding with Long Polling subprotocol)

Observe property (HTTP binding with Server Sent Event 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.

Observe property (HTTP binding with Server Sent Event subprotocol)

Observe property (HTTP binding with WebSocket subprotocol)

The following sequence illustrates application and network transactions to implement the observeproperty operation with an HTTP protocol binding using a WebSocket-based subprotocol.

Observe property (HTTP binding with a WebSocket subprotocol)

Action Interactions

Invoke action (HTTP binding)

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.

Invoke action (HTTP binding)

Event Interactions

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.

Subscribe, notify and unsubscribe event (HTTP binding with 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 Long Polling subprotocol.

Subscribe, notify, and unsubscribe event (HTTP binding with Long Polling subprotocol)

Subscribe, notify and unsubscribe event (HTTP binding with 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 the Server Sent Event subprotocol.

Subscribe, notify and unsubscribe event (HTTP binding with Server Sent Event subprotocol)

Subscribe, notify and unsubscribe event (HTTP binding with WebSocket 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.

Subscribe, notify and unsubscribe event (HTTP binding with WebSocket subprotocol)