From 835e1e45dd2d420ccbd0884f7a3faa377660325b Mon Sep 17 00:00:00 2001 From: Ben Francis Date: Thu, 22 Apr 2021 12:39:03 +0100 Subject: [PATCH 1/6] New structure for Protocol Binding section --- index.html | 167 ++++++++++++++++++++++++++++------------------------- 1 file changed, 89 insertions(+), 78 deletions(-) diff --git a/index.html b/index.html index 772ecf8..034ac54 100644 --- a/index.html +++ b/index.html @@ -98,17 +98,17 @@

- The WoT Profile Specification defines a Profiling Mechanism and a WoT Core Profile, + The WoT Profile Specification defines a Profiling Mechanism and a WoT Core Profile, which enables out of the box interoperability among things and devices. Out of the box interoperability implies, - that devices can be integrated into various application scenarios without - deep level adaptations. Typically only minor configuration operations are - necessary (such as entering a network key, or IP address) - to use the device in a certain scenario. + that devices can be integrated into various application scenarios without + deep level adaptations. Typically only minor configuration operations are + necessary (such as entering a network key, or IP address) + to use the device in a certain scenario. These actions can be done by anyone without specific training.

- The WoT Core Profile defines a set of constraints - and rules, which compliant thing descriptions have to adopt + The WoT Core Profile defines a set of constraints + and rules, which compliant thing descriptions have to adopt to guarantee interoperability.

@@ -977,12 +977,12 @@

Additional Constraints

object depths for properties. Parsing of a deeply nested structure is not possible on resource constrained devices. Therefore each - property MUST NOT exceed a maximum depth + property MUST NOT exceed a maximum depth of 5 levels of nested array or object - elements. It is RECOMMENDED to keep the nesting + elements. It is RECOMMENDED to keep the nesting of these elements below 4.

@@ -1453,80 +1453,91 @@

Recommended Practice

- +
- -

Protocol Binding

- -
This section is work in - progress and will undergo significant changes past FPWD - to incorporate experiences of implementations - in plug-fests and products.
-

- This section describes how the Core Data Model is - bound to different protocols. In addition to a set of - mapping rules, it defines additional behavior, e.g. - timeouts, error behavior, action semantics, etc. -

-
-

Common core data model

- The HTTP protocol binding is not meant to be exclusive, - the common core data model can be bound to other protocols as well. - The common core datamodel ensures interoperability across different protocols. +
+

Properties

+
+
readproperty
+
+
+
writeproperty
+
+
+
readallproperties
+
+
+
writeallproperties
+
+
+
readmultipleproperties
+
+
+
writemultipleproperties
+
+
+

+ Other operations under consideration include + observeproperty, unobserveproperty, + observeallproperties and + unobserveallproperties. +

+

+ These operations would require consesus on a default observe + mechanism for HTTP (e.g. Server Sent Events or WebSockets). +

+
- -
- Bindings for additional protocols can be defined in a future version of this specification, - or, already included in the current version.
- -
-

HTTP Protocol Binding

-

All communication is using JSON payloads over - HTTP(s). The content type header MUST be set to - "application/json".

- -
-

Properties

-

The HTTP verbs GET and PUT are mapped on - reading and writing a property - all other - protocol verbs return an error "405 Method - Not Allowed".

-
-

Note: Since HTTP does not provide a - pub/sub mechanism, the observe interaction - is not supported directly. The event - mechanism can be used instead to send - notifications on property changes.

-
-

Multiple properties can be set/get by - accessing the Properties endpoint.

+
+

Actions

+
+
invokeaction
-
-

Actions

-

Actions can be synchronous and asynchronous. - The current TD specification does not - distinguish these two cases and does not - describe a detailed mechanism.

-

The HTTP verb POST is mapped to invoking an - action on the actions endpoint - all other - protocol verbs return an error "405 Method - Not Allowed".

+
Other operations under consideration include + queryaction, updateaction and + cancelaction. These operations do not yet exist in + the WoT Thing Description specification (see + + #302 + ).
-
-

Events

-
- The candidate sub-protocols for events are - WebHooks, WebSockets, SSE and Long polling. - SSE and LongPolling are suggested as the - preferred candidates for a thing that provides - event affordances.
+
+
+

Events

+
+

+ Other operations under consideration include + subscribeevent, unsubscribeevent, + subscribeallevents, unsubscribeallevents, + readpastevents and readallpastevents. +

+

+ subscribeevent, unsubscribeevent, + subscribeallevents and + unsubscribeallevents would require consensus on a + default event subscription mechanism for HTTP (e.g. Server Sent + Events or WebSockets). +

+

+ subscribeallevents and + unsubscribeallevents do not yet exist in the WoT Thing + Description specification (see + + #1082 + ). +

+

+ readpastevents and readallpastevents do + not yet exist in the WoT Thing Description specification (see + + #892 + ). +

- -

External TD representations

@@ -1540,11 +1551,11 @@

Canonical TD representation

A canonical representation serves multiple purposes. - It is simplifying the parsing process, enables to identify + It is simplifying the parsing process, enables to identify equivalent TDs by simple string comparisons. Furthermore it allows the use of a simple signing mechanism, - such as Linked Data Proofs or JSON Web Signatures [[RFC7515]] and enables - identity checks on encrypted TDs. + such as Linked Data Proofs or JSON Web Signatures [[RFC7515]] and enables + identity checks on encrypted TDs.

The canonical JSON representation format of a TD adopts the JSON Canonicalization Scheme (JCS) defined by @@ -1554,7 +1565,7 @@

Canonical TD - +

Protocol Binding

+

+ This section defines a protocol binding which describes how a + Consumer + communicates with a + Web Thing + [[wot-architecture]] using JSON [[JSON]] payloads over + the HTTP [[HTTP11]] protocol. +

+

+ A Consumer or Web Thing conforming to the WoT Core Profile + MUST implement this protocol binding. +

Properties

readproperty
+

+ The URL of a Property resource to be used when reading + the value of a property MUST be obtained from a Canonical TD by + locating a + + Form inside the corresponding + + PropertyAffordance + for which the value of its op member is + readproperty and the + URI + scheme [[RFC3986]] of the value of its href member + is http or https. +

+

+ In order to read the value of a property, a Consumer MUST send + an HTTP request to a Web Thing with: +

    +
  • Method set to GET
    • +
  • URL set to the URL of the Property resource
    • +
  • Accept header set to application/json +
    • +
+

+ 
+          GET /things/lamp/properties/on HTTP/1.1
+          Host: mythingserver.com
+          Accept: application/json
+
+

+ If a Web Thing receives an HTTP request following the format + above and the Consumer has permission to read the corresponding + property, then upon successfully reading the value of the property + it MUST send an HTTP response with: +

    +
  • Status code set to 200
    • +
  • Content-Type header set to application/json +
    • +
  • A body with the value of the property serialized in JSON
    • +
+

+ 
+          HTTP/1.1 200 OK
+          Content-Type: application/json
+          false
+
+

+ If the property can not be read successfully then the Web Thing + MUST send an HTTP response with an HTTP error code which describes the + reason for the failure. E.g. +

+
    +
  • 400 Bad Request
    • +
  • 401 Unauthorized
    • +
  • 403 Forbidden
    • +
  • 404 Not Found
    • +
  • 500 Internal Server Error
    • +
writeproperty
+

+ The URL of a Property resource to be used when writing + the value of a property MUST be obtained from a Canonical TD by + locating a + + Form inside the corresponding + + PropertyAffordance + for which the value of its op member is + writeproperty and the + URI + scheme [[RFC3986]] of the value of its href member + is http or https. +

+

In order to write the value of a property, a Consumer MUST send + an HTTP request to a Web Thing with: +

    +
  • Method set to PUT
    • +
  • URL set to the URL of the Property resource
    • +
  • Accept header set to application/json +
    • +
  • Content-Type header set to application/json +
    • +
  • A body with a requested new value for the property serialized + in JSON
    • +
+

+ 
+          PUT /things/lamp/properties/on HTTP/1.1
+          Host: mythingserver.com
+          Content-Type: application/json
+          Accept: application/json
+          true
+
+

+ If a Web Thing receives an HTTP request following the format + above and the Consumer has permission to write the corresponding + property, then upon successfully writing the value of the + property it MUST send an HTTP response with: +

    +
  • Status code set to 200
    • +
  • Content-Type header set to application/json +
    • +
  • A body with the new value of the property serialized in JSON +
    • +
+

+ 
+          HTTP/1.1 200 OK
+          Content-Type: application/json
+          true
+
+

+ If the value of the property can not be written successfully then + the Web Thing MUST send an HTTP response with an HTTP error code + which describes the reason for the failure. E.g. +

+
    +
  • 400 Bad Request
    • +
  • 401 Unauthorized
    • +
  • 403 Forbidden
    • +
  • 404 Not Found
    • +
  • 500 Internal Server Error
    • +
readallproperties
+

+ The URL of a Properties resource to be used when + reading the value of all properties at once MUST be obtained from a + Canonical TD by locating a + + Form inside the top level + + forms member + for which the value of its op member is + readallproperties and the + URI + scheme [[RFC3986]] of the value of its href member + is http or https. +

+

+ In order to read the value of all properties, a Consumer MUST send + an HTTP request to a Web Thing with: +

    +
  • Method set to GET
    • +
  • URL set to the URL of the Properties resource +
    • +
  • Accept header set to application/json +
    • +
+

+ 
+          GET /things/lamp/properties HTTP/1.1
+          Host: mythingserver.com
+          Accept: application/json
+
+

+ If a Web Thing receives an HTTP request following the format + above, then upon successfully reading the value of the properties + to which the Consumer has permission to access, it MUST send an HTTP + response with: +

    +
  • Status code set to 200
    • +
  • Content-Type header set to application/json +
    • +
  • A body with the values of the properties serialized in JSON, + as an object keyed by property name
    • +
+

+ 
+          HTTP/1.1 200 OK
+          Content-Type: application/json
+          {
+            "on": false,
+            "level": 100
+          }
+
+

+ If the properties can not be read successfully then the Web Thing + MUST send an HTTP response with an HTTP error code which describes + the reason for the failure. E.g. +

+
    +
  • 400 Bad Request
    • +
  • 401 Unauthorized
    • +
  • 403 Forbidden
    • +
  • 404 Not Found
    • +
  • 500 Internal Server Error
    • +
writeallproperties
+

+ The URL of a Properties resource to be used when + writing the value of all properties at once MUST be obtained from a + Canonical TD by locating a + + Form inside the top level + + forms member + for which the value of its op member is + writeallproperties and the + URI + scheme [[RFC3986]] of the value of its href member + is http or https. +

+

+ In order to write the value of all writable properties at once, + a Consumer MUST send an HTTP request to a Web Thing with: +

    +
  • Method set to PUT
    • +
  • URL set to the URL of the Properties resource +
    • +
  • Content-Type header set to application/json +
    • +
  • Accept header set to application/json +
    • +
  • A body with requested new values for the writable properties + serialized in JSON, as an object keyed by property name
    • +
+

+ 
+          PUT /things/lamp/properties HTTP/1.1
+          Host: mythingserver.com
+          Content-Type: application/json
+          Accept: application/json
+          {
+            "on": true,
+            "level": 50
+          }
+
+

+ If a Web Thing receives an HTTP request following the format + above, then upon successfully writing the value of the properties + it MUST send an HTTP response with: +

    +
  • Status code set to 200
    • +
  • Content-Type header set to application/json +
    • +
  • A body with the new values of the properties serialized in + JSON, as an object keyed by property name
    • +
+

+ 
+          HTTP/1.1 200 OK
+          Content-Type: application/json
+          {
+            "on": true,
+            "level": 50
+          }
+
+

+ If the properties can not be written successfully then the Web Thing + MUST send an HTTP response with an HTTP error code which describes + the reason for the failure. E.g. +

+
    +
  • 400 Bad Request
    • +
  • 401 Unauthorized
    • +
  • 403 Forbidden
    • +
  • 404 Not Found
    • +
  • 500 Internal Server Error
    • +
readmultipleproperties
+

+ The URL of a Properties resource to be used when + reading the value of multiple properties at once MUST be obtained + from a Canonical TD by locating a + + Form inside the top level + + forms member + for which the value of its op member is + readmultipleproperties and the + URI + scheme [[RFC3986]] of the value of its href member + is http or https. +

+

+ In order to read the value of multiple properties, a Consumer MUST + send an HTTP request to a Web Thing with: +

    +
  • Method set to GET
    • +
  • URL set to the URL of the Properties resource +
    • +
  • Content-Type header set to application/json +
    • +
  • Accept header set to application/json +
    • +
  • A body with a list of the names of properties to be read + serialized in JSON, as an array of property names
    • +
+

+ 
+          GET /things/lamp/properties HTTP/1.1
+          Host: mythingserver.com
+          Accept: application/json
+          ["on", "level"]
+
+

+ If a Web Thing receives an HTTP request following the format + above, then upon successfully reading the values of the properties + it MUST send an HTTP response with: +

    +
  • Status code set to 200
    • +
  • Content-Type header set to application/json +
    • +
  • A body with the values of the properties serialized in JSON, + as an object keyed by property name
    • +
+

+ 
+          HTTP/1.1 200 OK
+          Content-Type: application/json
+          {
+            "on": false,
+            "level": 100
+          }
+
+

+ If the properties can not be read successfully then the Web Thing + MUST send an HTTP response with an HTTP error code which describes + the reason for the failure. E.g. +

+
    +
  • 400 Bad Request
    • +
  • 401 Unauthorized
    • +
  • 403 Forbidden
    • +
  • 404 Not Found
    • +
  • 500 Internal Server Error
    • +
writemultipleproperties
+

+ The URL of a Properties resource to be used when + writing the value of multiple properties at once MUST be obtained + from a Canonical TD by locating a + + Form inside the top level + + forms member + for which the value of its op member is + writemultipleproperties and the + URI + scheme [[RFC3986]] of the value of its href member + is http or https. +

+

+ In order to write the value of multiple properties at once, a + Consumer MUST send an HTTP request to a Web Thing with: +

    +
  • Method set to PUT
    • +
  • URL set to the URL of the Properties resource +
    • +
  • Content-Type header set to application/json +
    • +
  • Accept header set to application/json +
    • +
  • A body with requested new values for the writable properties + serialized in JSON, as an object keyed by property name
    • +
+

+ 
+          PUT /things/lamp/properties HTTP/1.1
+          Host: mythingserver.com
+          Content-Type: application/json
+          Accept: application/json
+          {
+            "on": true,
+            "level": 50
+          }
+
+

+ If a Web Thing receives an HTTP request following the format + above, then upon successfully writing the value of the properties + it MUST send an HTTP response with: +

    +
  • Status code set to 200
    • +
  • Content-Type header set to application/json +
    • +
  • A body with the new values of the properties serialized in + JSON, as an object keyed by property name
    • +
+

+ 
+          HTTP/1.1 200 OK
+          Content-Type: application/json
+          {
+            "on": true,
+            "level": 50
+          }
+
+

+ If the properties can not be written successfully then the Web Thing + MUST send an HTTP response with an HTTP error code which describes + the reason for the failure. E.g. +

+
    +
  • 400 Bad Request
    • +
  • 401 Unauthorized
    • +
  • 403 Forbidden
    • +
  • 404 Not Found
    • +
  • 500 Internal Server Error
    • +

@@ -1493,6 +1899,68 @@

writemultipleproperties

Actions

invokeaction
+

+ The URL of an Action resource to be used when invoking + an action MUST be obtained from a Canonical TD by locating a + + Form inside the corresponding + + ActionAffordance + for which the value of its op member is + invokeaction and the + URI + scheme [[RFC3986]] of the value of its href member + is http or https. +

+

In order to invoke an action on a Web Thing, a Consumer MUST send + an HTTP request to the Web Thing with: +

    +
  • Method set to POST
    • +
  • URL set to the URL of the Action resource
    • +
  • Accept header set to application/json +
    • +
  • Content-Type header set to application/json +
    • +
  • A body with an input to the action, if any, serialized in + JSON
    • +
+

+ 
+          POST /things/lamp/actions/fade HTTP/1.1
+          Host: mythingserver.com
+          Content-Type: application/json
+          Accept: application/json
+          {
+            "level": 100,
+            "duration": 5
+          }
+
+

+ If a Web Thing receives an HTTP request following the format + above and the Consumer has permission to invoke the corresponding + action, then upon successfully invoking the action it MUST send an + HTTP response with: +

+

The response to invoking an action needs to + be defined. Given not all actions can be completed within the + timeout period of an HTTP response, this may need to include a + reference to an action request resource in an action queue (see + + #302). +

+

+ If the action can not be invoked successfully then + the Web Thing MUST send an HTTP response with an HTTP error code + which describes the reason for the failure. E.g. +

+
    +
  • 400 Bad Request
    • +
  • 401 Unauthorized
    • +
  • 403 Forbidden
    • +
  • 404 Not Found
    • +
  • 418 I'm a teapot
    • +
  • 500 Internal Server Error
    • +
Other operations under consideration include queryaction, updateaction and @@ -1538,6 +2006,7 @@

Events

+

External TD representations

From f70ec7541da89ab40964e5f237270362cfe775b0 Mon Sep 17 00:00:00 2001 From: Ben Francis Date: Wed, 28 Apr 2021 16:12:17 +0100 Subject: [PATCH 3/6] Explicity define reading readable properties and writing writable properties --- index.html | 39 ++++++++++++++++++++------------------- 1 file changed, 20 insertions(+), 19 deletions(-) diff --git a/index.html b/index.html index ba92bd7..76fcd79 100644 --- a/index.html +++ b/index.html @@ -1632,15 +1632,15 @@
readallproperties

If a Web Thing receives an HTTP request following the format - above, then upon successfully reading the value of the properties - to which the Consumer has permission to access, it MUST send an HTTP - response with: + above, then upon successfully reading the values of all the + readable properties to which the Consumer has permission to + access, it MUST send an HTTP response with:

  • Status code set to 200
  • Content-Type header set to application/json
    • -
  • A body with the values of the properties serialized in JSON, - as an object keyed by property name
    • +
  • A body with the values of all readable properties serialized + in JSON, as an object keyed by property name

@@ -1707,14 +1707,14 @@ 
writeallproperties

If a Web Thing receives an HTTP request following the format - above, then upon successfully writing the value of the properties - it MUST send an HTTP response with: + above, then upon successfully writing the value of all writable + properties it MUST send an HTTP response with:

  • Status code set to 200
  • Content-Type header set to application/json
    • -
  • A body with the new values of the properties serialized in - JSON, as an object keyed by property name
    • +
  • A body with the new values of all writable properties + serialized in JSON, as an object keyed by property name

@@ -1765,8 +1765,8 @@ 
readmultipleproperties

                 
               
  • Accept header set to application/json
                 
    • 
-              
  • A body with a list of the names of properties to be read
-                serialized in JSON, as an array of property names
    • 
+              
  • A body with a list of the names of readable properties to be
+                read serialized in JSON, as an array of property names
    • 
             
           
    
           
    @@ -1777,14 +1777,14 @@ 
    readmultipleproperties
    
           
    
           
    
             If a Web Thing receives an HTTP request following the format
-            above, then upon successfully reading the values of the properties
-            it MUST send an HTTP response with:
+            above, then upon successfully reading the values of the requested
+            readable properties it MUST send an HTTP response with:
             
      
               
    • Status code set to 200
      • 
               
    • Content-Type header set to application/json
                 
      • 
-              
    • A body with the values of the properties serialized in JSON,
-              as an object keyed by property name
      • 
+              
    • A body with the values of the requested readable properties
+                serialized in JSON, as an object keyed by property name
      • 
             
    
           
    
           
    @@ -1851,14 +1851,15 @@ 
    writemultipleproperties
    
           
    
           
    
             If a Web Thing receives an HTTP request following the format
-            above, then upon successfully writing the value of the properties
-            it MUST send an HTTP response with:
+            above, then upon successfully writing the values of the requested
+            writable properties it MUST send an HTTP response with:
             
      
               
    • Status code set to 200
      • 
               
    • Content-Type header set to application/json
                 
      • 
-              
    • A body with the new values of the properties serialized in
-                JSON, as an object keyed by property name
      • 
+              
    • A body with the new values of the requested writable
+                properties serialized in JSON, as an object keyed by property
+                name
      • 
             
    
           
    
           
    
From e2ee023288513996b921d2a9679fd90417659c78 Mon Sep 17 00:00:00 2001
From: Ben Francis 
Date: Thu, 6 May 2021 18:19:51 +0100
Subject: [PATCH 4/6] Remove readmultipleproperties and writeallproperties

---
 index.html | 152 +++--------------------------------------------------
 1 file changed, 8 insertions(+), 144 deletions(-)

diff --git a/index.html b/index.html
index 76fcd79..2c41f1a 100644
--- a/index.html
+++ b/index.html
@@ -1664,150 +1664,6 @@ 
    readallproperties
    
             
  • 500 Internal Server Error
    •
    -
    -
    writeallproperties
    -

    - The URL of a Properties resource to be used when - writing the value of all properties at once MUST be obtained from a - Canonical TD by locating a - - Form inside the top level - - forms member - for which the value of its op member is - writeallproperties and the - URI - scheme [[RFC3986]] of the value of its href member - is http or https. -

    -

    - In order to write the value of all writable properties at once, - a Consumer MUST send an HTTP request to a Web Thing with: -

      -
    • Method set to PUT
      • -
    • URL set to the URL of the Properties resource -
      • -
    • Content-Type header set to application/json -
      • -
    • Accept header set to application/json -
      • -
    • A body with requested new values for the writable properties - serialized in JSON, as an object keyed by property name
      • -
    -

    - 
    -          PUT /things/lamp/properties HTTP/1.1
-          Host: mythingserver.com
-          Content-Type: application/json
-          Accept: application/json
-          {
-            "on": true,
-            "level": 50
-          }
-
    -

    - If a Web Thing receives an HTTP request following the format - above, then upon successfully writing the value of all writable - properties it MUST send an HTTP response with: -

      -
    • Status code set to 200
      • -
    • Content-Type header set to application/json -
      • -
    • A body with the new values of all writable properties - serialized in JSON, as an object keyed by property name
      • -
    -

    - 
    -          HTTP/1.1 200 OK
-          Content-Type: application/json
-          {
-            "on": true,
-            "level": 50
-          }
-
    -

    - If the properties can not be written successfully then the Web Thing - MUST send an HTTP response with an HTTP error code which describes - the reason for the failure. E.g. -

    -
      -
    • 400 Bad Request
      • -
    • 401 Unauthorized
      • -
    • 403 Forbidden
      • -
    • 404 Not Found
      • -
    • 500 Internal Server Error
      • -
    -
    -
    -
    readmultipleproperties
    -

    - The URL of a Properties resource to be used when - reading the value of multiple properties at once MUST be obtained - from a Canonical TD by locating a - - Form inside the top level - - forms member - for which the value of its op member is - readmultipleproperties and the - URI - scheme [[RFC3986]] of the value of its href member - is http or https. -

    -

    - In order to read the value of multiple properties, a Consumer MUST - send an HTTP request to a Web Thing with: -

      -
    • Method set to GET
      • -
    • URL set to the URL of the Properties resource -
      • -
    • Content-Type header set to application/json -
      • -
    • Accept header set to application/json -
      • -
    • A body with a list of the names of readable properties to be - read serialized in JSON, as an array of property names
      • -
    -

    - 
    -          GET /things/lamp/properties HTTP/1.1
-          Host: mythingserver.com
-          Accept: application/json
-          ["on", "level"]
-
    -

    - If a Web Thing receives an HTTP request following the format - above, then upon successfully reading the values of the requested - readable properties it MUST send an HTTP response with: -

      -
    • Status code set to 200
      • -
    • Content-Type header set to application/json -
      • -
    • A body with the values of the requested readable properties - serialized in JSON, as an object keyed by property name
      • -
    -

    - 
    -          HTTP/1.1 200 OK
-          Content-Type: application/json
-          {
-            "on": false,
-            "level": 100
-          }
-
    -

    - If the properties can not be read successfully then the Web Thing - MUST send an HTTP response with an HTTP error code which describes - the reason for the failure. E.g. -

    -
      -
    • 400 Bad Request
      • -
    • 401 Unauthorized
      • -
    • 403 Forbidden
      • -
    • 404 Not Found
      • -
    • 500 Internal Server Error
      • -
    -
    writemultipleproperties

    @@ -1894,6 +1750,14 @@

    writemultipleproperties
    These operations would require consesus on a default observe mechanism for HTTP (e.g. Server Sent Events or WebSockets).

    +

    + readmultipleproperties is currently excluded due to + the complexities of the request payload format and because it + doesn't add much functionality over readproperty and + readallproperties. + writeallproperties is currently excluded because it + is just a special case of writemultipleproperties. +

    From 4a35c44d2e1b261e94b375f75574d64e2350f195 Mon Sep 17 00:00:00 2001 From: Ben Francis Date: Thu, 6 May 2021 18:27:12 +0100 Subject: [PATCH 5/6] Change PUT responses from 200 to 204 --- index.html | 24 ++++-------------------- 1 file changed, 4 insertions(+), 20 deletions(-) diff --git a/index.html b/index.html index 2c41f1a..59cb076 100644 --- a/index.html +++ b/index.html @@ -1573,17 +1573,11 @@
    writeproperty
    property, then upon successfully writing the value of the property it MUST send an HTTP response with:
      -
    • Status code set to 200
      • -
    • Content-Type header set to application/json -
      • -
    • A body with the new value of the property serialized in JSON -
      • +
    • Status code set to 204

    -          HTTP/1.1 200 OK
-          Content-Type: application/json
-          true
+          HTTP/1.1 204 No Content

    If the value of the property can not be written successfully then @@ -1710,21 +1704,11 @@

    writemultipleproperties
    above, then upon successfully writing the values of the requested writable properties it MUST send an HTTP response with:
      -
    • Status code set to 200
      • -
    • Content-Type header set to application/json -
      • -
    • A body with the new values of the requested writable - properties serialized in JSON, as an object keyed by property - name
      • +
    • Status code set to 204

    -          HTTP/1.1 200 OK
-          Content-Type: application/json
-          {
-            "on": true,
-            "level": 50
-          }
+          HTTP/1.1 204 No Content

    If the properties can not be written successfully then the Web Thing From aa9d6fe9ca73ba4a9f7673a8f00e0dd98c4976d9 Mon Sep 17 00:00:00 2001 From: Ben Francis Date: Thu, 6 May 2021 19:15:04 +0100 Subject: [PATCH 6/6] Define a finite set of recommended error codes --- index.html | 92 ++++++++++++++++++------------------------------------ 1 file changed, 31 insertions(+), 61 deletions(-) diff --git a/index.html b/index.html index 59cb076..13e30cf 100644 --- a/index.html +++ b/index.html @@ -1518,18 +1518,6 @@

    readproperty
    Content-Type: application/json false -

    - If the property can not be read successfully then the Web Thing - MUST send an HTTP response with an HTTP error code which describes the - reason for the failure. E.g. -

    -
      -
    • 400 Bad Request
      • -
    • 401 Unauthorized
      • -
    • 403 Forbidden
      • -
    • 404 Not Found
      • -
    • 500 Internal Server Error
      • -
    writeproperty
    @@ -1579,18 +1567,6 @@
    writeproperty
               HTTP/1.1 204 No Content
    -

    - If the value of the property can not be written successfully then - the Web Thing MUST send an HTTP response with an HTTP error code - which describes the reason for the failure. E.g. -

    -
      -
    • 400 Bad Request
      • -
    • 401 Unauthorized
      • -
    • 403 Forbidden
      • -
    • 404 Not Found
      • -
    • 500 Internal Server Error
      • -
    readallproperties
    @@ -1645,18 +1621,6 @@
    readallproperties
    "level": 100 } -

    - If the properties can not be read successfully then the Web Thing - MUST send an HTTP response with an HTTP error code which describes - the reason for the failure. E.g. -

    -
      -
    • 400 Bad Request
      • -
    • 401 Unauthorized
      • -
    • 403 Forbidden
      • -
    • 404 Not Found
      • -
    • 500 Internal Server Error
      • -
    writemultipleproperties
    @@ -1710,18 +1674,6 @@
    writemultipleproperties
               HTTP/1.1 204 No Content
    -

    - If the properties can not be written successfully then the Web Thing - MUST send an HTTP response with an HTTP error code which describes - the reason for the failure. E.g. -

    -
      -
    • 400 Bad Request
      • -
    • 401 Unauthorized
      • -
    • 403 Forbidden
      • -
    • 404 Not Found
      • -
    • 500 Internal Server Error
      • -

    @@ -1797,19 +1749,6 @@

    invokeaction
    #302).

    -

    - If the action can not be invoked successfully then - the Web Thing MUST send an HTTP response with an HTTP error code - which describes the reason for the failure. E.g. -

    -
      -
    • 400 Bad Request
      • -
    • 401 Unauthorized
      • -
    • 403 Forbidden
      • -
    • 404 Not Found
      • -
    • 418 I'm a teapot
      • -
    • 500 Internal Server Error
      • -
    Other operations under consideration include queryaction, updateaction and @@ -1853,6 +1792,37 @@

    Events

    +
    +

    Error Responses

    +

    + If any of the operations defined above are unsuccessful then + the Web Thing MUST send an HTTP response with an HTTP error code which + describes the reason for the failure. It is RECOMMENDED that error + responses use one of the following HTTP error codes: +

    +
      +
    • 400 Bad Request
      • +
    • 401 Unauthorized
      • +
    • 403 Forbidden
      • +
    • 404 Not Found
      • +
    • 500 Internal Server Error
      • +
    +

    + Web Things MAY respond with other valid HTTP error codes + (e.g. 418 I'm a teapot), but Consumers MAY interpret + those error codes as a generic 4xx or 5xx + error with no special defined behaviour. +

    +

    + If we define the finite set of error responses as above then we + should also define what a Consumer should do if it receives a 3xx + redirect type response. +

    +

    + If an HTTP error response contains a body, the content of that body + MUST conform with with the Problem Details format [[RFC7807]]. +

    +