links vs. forms

[benfrancis]

The current Thing Description specification uses the term form to refer to links which have a href, mediaType and rel. This was changed in #62 apparently due to some complexity introduced by the protocol bindings work.

I understand this is meant to represent an analogy with "web forms". Can someone explain this rationale further? links seems like a much more obvious term to use here.

[sebastiankb]

Intention of the renaming was that this container contains all communication metadata and how the message is or has to be constructed for invoking an interaction. Some detail explanations and use cases are given in the Web of Things (WoT) Protocol Binding Templates deliverable.

[mkovatsc]

Taken from #88:

Thinking of the TD as "HTML for Things", this can be seen as follows: They are not links to related Things (pages) or to include externalized metadata (e.g., stylesheet). They are about the operational/live data, and hence similar to forms that tell the client how to formulate a request to interact with the Thing ("active" page / REST resource). For Actions, this is the most clear, as they might need a request payload to be described (e.g., media type). For Properties it is like a form with method="GET" that allows to parameterize what to get/read.

Web links express relations to other Web resources. "WoT links" express relations to other Things.

[benfrancis]

Taken from #88:

This is an interesting analogy, but I'm not sure "HTML for Things" is the best way to describe the Thing Description. Not least because the Thing Description is a machine-readable representation of a resource which may also have a human-readable HTML representation (in Mozilla's gateway implementation we use HTTP content negotiation for the server to decide whether to send a JSON representation or an HTML representation for the same URL).

I see the Thing Description format more like an Interface Description Language (IDL) which describes an HTTP/CoAP/WebSocket API for a Thing using a HATEOAS approach. The Thing Description is a top level resource which links to other resources using link relations (see here for an equivalent example serialised in XML).

In this way a Thing is more like a website or web app which consists of multiple resources (pages), rather than a represented as a single resource (page).

The forms approach is an interesting way of leaving the mechanics of the API for a Thing completely open ended and leaving it up to the Thing Description to define an implementation-specific protocol binding for each Thing. Would this not be unnecessary if for example an HTTP binding specification defined how thing, property, action and event resources could be interacted with using specific HTTP verbs? e.g. use a PUT on a property URL to set a property?

Apart from custom headers (which hopefully aren't necessary), everything else could be described with a link relation.

For a JSON Thing Description served over HTTP an http:// scheme and application/json MIME type could be assumed as the default, unless specified otherwise (e.g. a coap:// URL and application/cbor MIME type as in your example, although in this case you might also want to serve the Thing Description itself as CBOR over CoAP...)

[mkovatsc]

Let's continue this in #88 only.