HTTP

This section describes the mapping between the high-level actions that can be executed on a Thing and the messages exchanged with the server when using the HTTP Protocol Binding.

All messages are serialized in JSON format.

Form elements

Form elements produced by the HTTP binding vary depending on the type of interaction. All forms contain the following fields:

Field	Description
op	Interaction verb (e.g. readproperty) associated with this form element.
href	The HTTP URL used to interface with the Thing server for this interaction verb.
mediaType	This field will always contain the MIME media type for JSON.

Interaction Model mapping

Note

The HTTP binding adopts the long-polling pattern to deal with server-side messages. In practice, this means that the server will keep the connection open on requests to the action invocation, property subscription and event subscription endpoints until a value is emitted or a timeout occurs.

Read Property

Form:

{
    "op": "readproperty",
    "contentType": "application/json",
    "href": "http://<host>:<port>/<thing_name>/property/<property_name>"
}

Request:

GET http://<host>:<port>/<thing_name>/property/<property_name>

Response:

HTTP 200

{
    "value": <property_value>
}

Write Property

Form:

{
    "op": "writeproperty",
    "contentType": "application/json",
    "href": "http://<host>:<port>/<thing_name>/property/<property_name>"
}

Request:

PUT http://<host>:<port>/<thing_name>/property/<property_name>

{
    "value": <property_value>
}

Response:

HTTP 200

Invoke Action

Form:

{
    "op": "invokeaction",
    "contentType": "application/json",
    "href": "http://<host>:<port>/<thing_name>/action/<action_name>"
}

An action invocation can be started with a POST request:

POST http://<host>:<port>/<thing_name>/action/<action_name>

{
    "input": <action_argument>
}

A unique UUID will be assigned to the ongoing invocation and returned in the response:

HTTP 200

{
    "invocation": "/invocation/<uuid>"
}

The status of the invocation can be retrieved from that URL:

GET http://<host>:<port>/invocation/<uuid>

The response will contain the final result or an error message:

HTTP 200

{
    "done": <boolean>,
    "result" <result_value>,
    "error": <error_message>
}

Observe Property changes

Form:

{
    "op": "observeproperty",
    "contentType": "application/json",
    "href": "http://<host>:<port>/<thing_name>/property/<property_name>/subscription"
}

Subscriptions are automatically managed by the HTTP binding. A subscription is initialized on each request and cancelled after a value is emitted:

GET http://<host>:<port>/<thing_name>/property/<property_name>/subscription

The response format is the same as the read property verb:

HTTP 200

{
    "value": <property_value>
}

Observe Event

Form:

{
    "op": "subscribeevent",
    "contentType": "application/json",
    "href": "http://<host>:<port>/<thing_name>/event/<event_name>/subscription"
}

Request:

GET http://<host>:<port>/<thing_name>/event/<event_name>/subscription

Response:

HTTP 200

{
    "payload": <event_payload>
}

Please note that subscriptions are also managed automatically, as occurs in the observe property case.