What level of detail is acceptable for default HTTP bindings?

[benfrancis]

Currently the HTTP Binding document specifies a default HTTP method for 7 of the 18 well-known operation types defined in the WoT Thing Description 1.1 specification:

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"

I have two key questions:

• Do you think it is feasible to define defaults for the full set of 18 operations?
• What level of detail do you think would be acceptable for these default bindings?

I've previously shared a WoT HTTP Binding 2.0 strawman proposal which proposes moving the content of at least the protocol binding section of the HTTP Basic Profile into the HTTP Binding document as defaults. The intention would be that the content of the protocol binding section of the HTTP SSE Profile would also be moved into a binding document, either the HTTP Binding or a seperate Server-Sent Events Binding. These defaults would then be referenced from Profiles rather than defined in them.

But what is an appropriate level of detail for a default binding? At one extreme we have the current very basic definition a single default term for each operation in a table as in the current HTTP Binding document, and at the other extreme we have the protocol bindings for action operations in the current WoT Profiles 1.0 specification which uses normative assertions to define what almost amounts to a sub-protocol for an action queue with dynamic resources and a data schema for action status.

My hope is that with Thing Description 2.0 the action operations will be better defined, and Thing Descriptions will be more expressive, such that the complicated actions bindings we created in 1.0 will not be necessary, though it remains to be seen how that will work.

What is an acceptable default binding?

• Must defaults only take the form of tables of default values for vocabulary terms?
• Can all terms have defaults (e.g. a default content type in an HTTP header)?
• Can bindings define default response codes?
• Can bindings define default error formats?
• Can bindings define default data schemas (e.g. for a queryaction response or a readmultipleproperties request)?
• Can bindings include written assertions which prescribe certain behaviour?

I think it is important to clearly answer these questions because the ability to define more detailed default bindings for the full set of WoT operations in binding documents is really a pre-requisite for the proposed new approach to profiles outlined in the WoT Profiles 2.0 Use Cases & Requirements document, where profiles constrain a fixed set of extension points (protocol bindings being one of them), but do not themselves define protocol bindings.

What do you think?

CC @egekorkan @mjkoster

P.S. If this issue belongs in the new wot-binding-registry repo then please let me know.

[egekorkan]

P.S. If this issue belongs in the new wot-binding-registry repo then please let me know.

First of all no, since this is really about the HTTP binding.

Do you think it is feasible to define defaults for the full set of 18 operations?

Not right now I would say until we agree on what is the default for async operations like observeproperty etc. However, it is possible.

What level of detail do you think would be acceptable for these default bindings?

Anything needed to map the operation should be possible. I will answer below regarding details.

Must defaults only take the form of tables of default values for vocabulary terms?

No rule so far.

Can all terms have defaults (e.g. a default content type in an HTTP header)?

So far, the content type is separated from the protocol binding. We can have a discussion on this, i.e. whether a protocol binding can define the default for the content type. I would say it can but doesn't have to.

Can bindings define default response codes?

Why not. Just that the current way of describing the response code is not used much. Also, given that there are multiple possible responses, it would get messy to describe this. In all cases, we should give implementation guidance and work on the expressivity to describe it nicely. Until then, it would be out of band.

Can bindings define default error formats?

That can get application specific from my point of view. While there is value in describing the error codes, I also don't see people doing that much with their TDs. The error format is thus not known in advance to the Consumer.

Can bindings define default data schemas (e.g. for a queryaction response or a readmultipleproperties request)?

No as we break the abstraction in that case. For meta operations, there is a gap in the spec so there is no abstraction to begin with though...

Can bindings include written assertions which prescribe certain behaviour?

Could you give examples? I would say no as protocol has nothing to do with behavior unless the proocol is stateful, which is not the case for HTTP.

[benfrancis]

@egekorkan wrote:

First of all no, since this is really about the HTTP binding.

Will the individual binding documents (at least the ones written by the WoT WG) live in this repository?

Not right now I would say until we agree on what is the default for async operations like observeproperty etc. However, it is possible.

I assume the options when using the http:// URI scheme are basically long-polling, SSE or Webhooks. Arguably long-polling is the most native to HTTP since it doesn't require any special semantics, but it's also the least efficient.

If an SSE binding was defined inside the HTTP binding document then the document doesn't necessarily have to prescribe a default eventing mechanism, just let developers opt-in to it using "subprotocol": "sse", then define defaults for the SSE binding for when it is opted into. That way the HTTP Binding could have a full set of default bindings, but developers opt-in to the event-based ones.

Theoretically the same could be done for long-polling and Webhooks "subprotocols" as well if there was a demand for that.

So far, the content type is separated from the protocol binding. We can have a discussion on this, i.e. whether a protocol binding can define the default for the content type. I would say it can but doesn't have to.

Ideally I would like it if the default HTTP bindings for certain operations could define a default Accept or Content-type header (with application/json as the value). Since the global default of application/json was removed, the Common Definitions proposal may provide a way to define a Thing-wide default contentType in a Thing Description, but if you just rely on that then you need a way to specify when there shouldn't be an Accept or Content-Type header (e.g. no Accept header when the response is expected to have no body or no Content-Type header when the request is expected to have no body). Without some solution for this you always have to specify headers in every single Form.

Defining a default content type for an SSE binding is a bit more complicated because we tend to wrap one content type inside another (e.g. application/json inside text/event-stream). My preferred solution to that is that text/event-stream is always assumed based on the "subprotocol":"sse", then the contentType member in TDs is assumed to be wrapped inside that format. In TD 1.1 where application/json is the global default that made Forms quite simple, but now we may need to specify something in Common Definitions to avoid having to specify "contentType":"application/json" in every single Form that uses the SSE binding.

Why not. Just that the current way of describing the response code is not used much. Also, given that there are multiple possible responses, it would get messy to describe this. In all cases, we should give implementation guidance and work on the expressivity to describe it nicely. Until then, it would be out of band.

What is the current way of describing the response code in HTTP? I don't see a vocabulary term for that, though I remember seeing examples TDs in the past which specified this.

Some examples of potential defaults:

• A readproperty request would get a 200 OK response by default.
• A writeproperty request would get a 204 No Content response by default.
• A synchronous invokeaction request with an ouput ("synchronous":true and output set) would respond with 200 OK by default.
• A synchronous invokeaction request without an output ("synchronous":true and output not set) would respond with a 204 No Content response by default.
• An asynchronous invokeaction request ("synchronous":false in a TD) would respond with a 201 Created response by default.
• A queryaction request would get a 200 OK response by default.
• A cancelaction request would get a 204 No Content response by default.
• An observeproperty request using the sse subprotocol ("subprotocol":"sse") would get a 200 OK response by default.
• A subscribeevent request using the sse subprotocol ("subprotocol":"sse") would get a 200 OK response by default.

That can get application specific from my point of view. While there is value in describing the error codes, I also don't see people doing that much with their TDs. The error format is thus not known in advance to the Consumer.

I agree that this doesn't seem to be commonly used and it may be tricky to define defaults. Currently as far as I can tell there isn't even a way to define a particular (error) response code in an AdditionalExpectedResponse in a TD.

No as we break the abstraction in that case. For meta operations, there is a gap in the spec so there is no abstraction to begin with though...

I agree it feels wrong to define fixed payload formats in a protocol binding document, but this is something we are going to have to solve one way or another because apart from payloads to describe action status there are still lots of other gaps in how to define payload formats in the Thing Description specification. I understand this is being looked at via the manageable affordances and data mapping topics, and I have some thoughts there to share separately.

Could you give examples? I would say no as protocol has nothing to do with behavior unless the proocol is stateful, which is not the case for HTTP.

Hmm, maybe behaviour was the wrong word. What I mean is that the "protocol bindings" in profiles are currently written in terms of assertions which clarify lots of details, some of which would not be easy to express declaratively in a TD. My assumption is that if we are limited to expressing these bindings as "defaults" of vocabulary terms in a TD then some of this detail is likely to be lost. I think I would need to do a detailed review of all of those assertions to figure out what we would be losing.

As a simple example, in a queryallactions response there is an assertion which says "Each array in the result object MUST be sorted in reverse chronological order such that the most recent action request appears first." I can't think of an obvious way to express that in a TD.

There are other assertions that do things like prescribe a specific status code for particular success or error conditions, which may also difficult to express as just a table of default values for terms.

[benfrancis]

See #361 for discussion of a potential SSE Binding inside the HTTP Binding document.