From b75632918c8a6da6836694db6126cdd419fe6286 Mon Sep 17 00:00:00 2001
From: Luca Barbato The normative HTTP Basic Profile is complemented by two
- informative profiles for events: The HTTP SSE Profile
+ The normative HTTP Basic Profile is complemented by two
+ informative profiles for events: The HTTP SSE Profile
and the HTTP Webhook Profile.
-
+
In the current version of this document these event bindings are provided in informative
sections, to illustrate how these event mechanisms could be supported in other profiles.
It is planned that future versions of this document normatively define
+ It is planned that future versions of this document normatively define
these event mechanisms.
Future versions of this document may contain other profiles, - e.g. a profile for digital twins and a profile for resource constrained devices.
+ e.g. a profile for digital twins and a profile for resource constrained devices.
- It is REQUIRED to provide a title
that can be automatically rendered in a non-visual way
+ It is REQUIRED to provide a title
that can be automatically rendered in a non-visual way
(e.g. using a screen reader)
for things that may be used in deployments with users with disabilities.
- It is highly RECOMMENDED to provide a description
that can be automatically rendered in a non-visual way
+ It is highly RECOMMENDED to provide a description
that can be automatically rendered in a non-visual way
(e.g. using a screen reader)
for things that may be used in deployments with users with disabilities.
Authors of Thing Descriptions should be aware that units - that are common in their geographic region are not globally applicable + that are common in their geographic region are not globally applicable and may lead to misinterpretation with drastic consequences.
- It is highly RECOMMENDED to provide a unit
,
+ It is highly RECOMMENDED to provide a unit
,
if a value has a physical quantity.
- It is highly RECOMMENDED to use the metric system (SI units) + It is highly RECOMMENDED to use the metric system (SI units) for devices that are used in global deployments.
- All date and time values MUST use the date-time
format
+ All date and time values MUST use the date-time
format
defined in [[RFC3339]].
@@ -645,22 +645,22 @@Security
Conformant Consumers MUST support all of these security schemes.
- +A Thing MAY implement multiple security schemes.
- +- Conformant Consumers MUST support security bootstrapping for all + Conformant Consumers MUST support security bootstrapping for all implemented security schemes, as defined in Security Bootstrapping in the WoT Discovery [[wot-discovery]] specification.
- +- Conformant Things which require authentication in order to retrieve + Conformant Things which require authentication in order to retrieve their Thing Description MUST implement security bootstrapping, as - defined in + defined in Security Bootstrapping in the WoT Discovery [[wot-discovery]] specification.
@@ -670,7 +670,7 @@Security
Discovery
- A Web Thing's Thing Description [[wot-thing-description]] MUST be + A Web Thing's Thing Description [[wot-thing-description]] MUST be retrievable from a Thing Description Server [[wot-architecture11]] using an HTTP @@ -687,7 +687,7 @@
Links
Hypermedia links in the HTTP Profiles are significantly constrained to ensure a common interpretation and interoperability between things and consumers.
- +The following keywords are defined for links in the HTTP profiles and MAY be present in profile-compliant TDs with the constraints defined by this section. @@ -698,7 +698,7 @@
Links
These other link types MAY be ignored by all profile-compliant consumers. - +These links enable consumers to interpret linked content that is provided by the link target in an unambiguous way. @@ -800,7 +800,7 @@
Media Types for Link Targets
The following media types from IANA MAY be used as the link targets of profile compliant TDs with the constraints in this section. - Other media types MAY + Other media types MAY be present in a TD, however their heir interpretation is undefined in the context of the HTTP profiles and they MAY be ignored by all profile-compliant consumers.@@ -868,7 +868,7 @@
Media Types for Link Targets
- + If a Consumer encounters a link with "rel": "service-doc" and "type": "text/plain", "type": "text/html" or "type": "text/pdf", and is capable of rendering documents in the provided format, then it SHOULD interpret the link as a @@ -877,7 +877,7 @@
Media Types for Link Targets
- + If a Consumer encounters a link with "rel": "item" and "type": "application/td+json" and is capable of rendering a hierarchical tree of Things, then it should interpret the link as an indication that the target is a sub-Thing of @@ -886,7 +886,7 @@
Media Types for Link Targets
- + If a Consumer encounters a link with "rel": "collection" and "type": "application/td+json" and is capable of rendering a @@ -976,7 +976,7 @@
@@ -1132,7 +1132,7 @@HTTP Basic Profile
In order to conform with the HTTP Basic Profile, Web Things and Consumers MUST also conform with all of the assertions in the - Common Constraints + Common Constraints section.
readproperty
URL set to the URL of the Property
resource- + Accept
header set toapplication/json
GET /things/lamp/properties/on HTTP/1.1 @@ -1452,32 +1452,32 @@
invokeaction
- - If the
synchronous
member of the + If thesynchronous
member of theActionAffordance
- [[wot-thing-description11]] is set totrue
then the Web + [[wot-thing-description11]] is set totrue
then the Web Thing MUST respond with a Synchronous Action Response.- - If the
synchronous
member of the + If thesynchronous
member of theActionAffordance
- [[wot-thing-description11]] is set tofalse
then the Web + [[wot-thing-description11]] is set tofalse
then the Web Thing MUST respond with an Asynchronous Action Response.- - If the
synchronous
member of the + If thesynchronous
member of theActionAffordance
- [[wot-thing-description11]] isundefined
then the Web - Thing MAY respond with either a + [[wot-thing-description11]] isundefined
then the Web + Thing MAY respond with either a Synchronous Action Response or Asynchronous Action Response. @@ -1565,7 +1565,7 @@
ActionStatus
objecthref
The [[URL]] of an ActionStatus
resource which - can be used byqueryaction
and + can be used byqueryaction
andcancelaction
operations, the URI scheme [[RFC3986]] of which MUST resolve to @@ -1580,8 +1580,8 @@
ActionStatus
objecttimeRequested
A timestamp indicating the time at which the Thing received - the request to execute the action. (See - Date Format for date format + the request to execute the action. (See + Date Format for date format constraints). optional @@ -1592,8 +1592,8 @@
ActionStatus
objectA timestamp indicating the time at which the Thing successfully completed executing the action, or failed to - execute the action. (See - Date Format for date format + execute the action. (See + Date Format for date format constraints). optional @@ -2223,8 +2223,8 @@It is RECOMMENDED that the identifier is a timestamp representing the time at which the - property changed (see - Date Format for date format + property changed (see + Date Format for date format constraints).
observeproperty
@@ -2382,8 +2382,8 @@below). It is RECOMMENDED that the identifier is a timestamp - representing the time at which the property changed (see - Date Format for date format + representing the time at which the property changed (see + Date Format for date format constraints).
observeallproperties
@@ -2557,8 +2557,8 @@below). It is RECOMMENDED that the identifier is a timestamp - representing the time at which the event ocurred (see - Date Format for date format + representing the time at which the event ocurred (see + Date Format for date format constraints).
subscribeevent
@@ -2805,17 +2805,17 @@Introduction
A Webhook is similar to a callback mechanism in programming languages. Consumers can subscribe to events they are interested in by registering a listener with the event endpoint. When the event condition occurs, the WebThing - is notifying all listeners with a corresponding event message, which is transmitted over HTTP(s). - The event message contains details about the event, such as timestamp, event type, + is notifying all listeners with a corresponding event message, which is transmitted over HTTP(s). + The event message contains details about the event, such as timestamp, event type, event source etc. in the data payload.- Depending on the deployment scenarios and integration requirements for existing consumers, it may be + Depending on the deployment scenarios and integration requirements for existing consumers, it may be required to use specific data payload formats (e.g. Cloud Events). - When a listener receives an event message in a data payload, in many cases it just acknowledges the + When a listener receives an event message in a data payload, in many cases it just acknowledges the successful reception of the event. - Additionally, it may provide a dataResponse payload, which provides a back-channel that can be used - to communicate further details from the consumer to the WebThing. -
+ Additionally, it may provide a dataResponse payload, which provides a back-channel that can be used + to communicate further details from the consumer to the WebThing. +Depending on the use case, a single listener for multiple things and multiple event types MAY be used. @@ -2928,7 +2928,7 @@
Message Format
TODO: Describe data and dataResponse schemas. - +Protocol Binding
@@ -2999,7 +2999,7 @@
subscribeevent
The subscription payload contains the URI for the event message listener - in the field with the
callbackURI
key. + in the field with thecallbackURI
key.