2.0 - Forms and Links href are not the same

[flatsiedatsie]

This could very well be a bug in the Candle code, but I thought I'd share since I can't imagine how the minute differences in Candle could have caused this.

In the screenshot below you can see how the forms href has an unexpected "properties" at the end:

My assumption is that "forms is the new links", and that for 2.0 the idea is that forms will be prefered, and that the hrefs should match. Is that correct?

[benfrancis]

My assumption is that "forms is the new links", and that for 2.0 the idea is that forms will be prefered, and that the hrefs should match. Is that correct?

You're correct that links are being replaced by forms in many instances, this is in order to be compliant with W3C WoT standards. But what you're looking at here are two different API endpoints with two different purposes.

The first endpoint is a Properties resource providing readallproperties and writemultipleproperties operations from the new W3C WoT HTTP Basic Profile. This is a replacement for the link to the Properties resource in the legacy Web Thing REST API.

The second endpoint is a WebSocket resource which provides an alternate API for all operations on the device using WebSockets. This still exposes the legacy Web Thing WebSocket API. Whilst the WebSocket sub-protocol is being standardised via the Web Thing Protocol Community Group, in WoT Thing Description 1.1 there is still no way to properly express this endpoint using forms, which is why it's currently still a link. See #2882 and w3c/wot-thing-description#1070 for discussion around this.

In summary: Property, Action, Event, Properties, Actions and Events resources will all switch from using links to using forms. The only links left will probably be:

• The top level alternate link to a WebSocket endpoint (unless we end up adding a separate WebSocket form to every interaction affordance)
• A top level alternate link to an HTML representation of a Thing (if it has a custom web interface)
• Any additional links that add-ons provide

Hope this makes sense.

Note that this was all discussed in #2806

[flatsiedatsie]

Wow, that's a very detailed explanation :-) I still don't understand 100%, but it's interesting. It clearly "works as designed". Thank you.

[flatsiedatsie]

Small practical question: in the "thing root" there is an attribute called "href" which does give the direct URL ending with the device ID. Then inside a property there is no similar "href". But here the forms can be used to extract the property ID.

Aside from the spec, perhaps there could be a practical way for the gateway to give both ID's with one consistent method? With the links situation you could get both by getting the first link in the list and extracting the last part of the path.

Maybe properties could also have a href in them?

Or even better: what if things have an thing_id attribute, and properties had a property_id attribute? That would make it simpler to create addons, as getting the device and property ID is so common.

Just thinking out loud.

[benfrancis]

Wow, that's a very detailed explanation :-)

That's unfortunately what happens when you ask a W3C specification editor a simple question about a specification 😂

in the "thing root" there is an attribute called "href" which does give the direct URL ending with the device ID

There is at the moment, but that's going away in 2.0, see #2856.

The ID of the Thing is provided by its id member, which according to the specification can be any unique URI (not just HTTP URLs) but WebThings Gateway always uses the URL of the Thing Description so you can get it from there instead if you want.

Note that the ID of the Thing is the full URL, not just the fragment at the end which may be of interest to an adapter add-on.

Then inside a property there is no similar "href".

Every PropertyAffordance has a Form with a href member which is resolved against the base member of the Thing to get the full URL of the property resource. The last fragment of that URL is what the WebThings Gateway router uses to identify a property to add-on adapters.

Note that the URL structure is not standardised in the W3C specification so that assumption only works for WebThings Gateway. There's no such thing as a "property ID" in the W3C specification, only the key of its PropertyAffordance in the properties Map and one or more href members in forms.

Aside from the spec, perhaps there could be a practical way for the gateway to give both ID's with one consistent method?

First of all, I'm currently in the process of trying to remove anything non-standard from Thing Descriptions so I'd rather not add anything new if not necessary. Anything we need to keep (like floorplanX, floorplanY, layoutIndex, selectedCapability etc.) will ideally be prefixed using JSON-LD contexts (e.g. wt:floorplanX). For now I'm just including both the W3C context and WebThings context without a prefix, but that risks name collisions in the future.

With the links situation you could get both by getting the first link in the list and extracting the last part of the path. Maybe properties could also have a href in them?

Forms provide exactly the same thing, though it's risky to assume it's the first form in the array. Technically you should check that it's an HTTP URL and doesn't have a different op value because there will be multiple forms using different protocols in the future (e.g. one URL for reading the property and another URL for observing the property using Server-Sent events, though for WebThings gateway I expect those two URLs will be the same). See the algorithm for readproperty for an an example of how to pick the right form if you want to do it properly.

Or even better: what if things have an thing_id attribute, and properties had a property_id attribute? That would make it simpler to create addons, as getting the device and property ID is so common.

What would that contain that would be any different to the key of the PropertyAffordance in the properties Map or the last fragment of the href of the Form? You can already get this value from either of those places in WebThings Gateway.

Just thinking out loud.

Feel free to make suggestions to the W3C WoT Working Group!

As you can see, there are lots of changes coming to the API in 2.0, so I don't recommend programming against that unless you've familiarised yourself with the latest drafts of the WoT Thing Description, WoT Discovery and WoT Profile specifications because you may be making incorrect assumptions about what terms in the Thing Description mean.

Those specifications don't make for light reading so I plan to write some simpler documentation of the gateway's API once the implementation is complete, along the lines of the current Web Thing API document but more like an MDN style explainer of the W3C specifications.