Add op to support PATCH

[mmccool]

In the TD Directory/Discovery discussion, we recently ran into a problem where we wanted to support both PUT and PATCH in the same interaction, but had no way to distinguish them in the Scripting API. (see w3c/wot-discovery#160). We will work around this for now by putting these in different interactions, but would like to suggest that an op that maps to PATCH could be added... perhaps "patchproperty". But there are still issues around data schemas and contentTypes to resolve (e.g. is contentType and schema the same, or different? If the same, how is the patch formed?)

[egekorkan]

I would suggest updateproperty since that can maybe give way to the updateaction that was in discussion in #899

[egekorkan]

By the way, it seems that the not well-argumented need to have a TD for the TDD is creating and has created issues in the TD spec that are resulting in some new features. I am not entirely convinced by the need to have a TD for the TDD when the API is for now only focused on HTTP. Why not simply use an Open API document? There was the argument that this way people can use the same tools that they use for parsing TDs but I feel that this argument is too weak. For a proper HTTP API like the TDD API is, I don't think that TD is the right technology. I also think that the TDD is not a Thing, thus it makes less sense to have a TD for it but maybe that is a more subjective discussion.

[benfrancis]

I don't think a patchproperty op is strictly necessary to distinguish between PUT and PATCH since a client can just use the htv:methodName to distinguish between the two. They are both write operations and there's already another interaction (createThing) in the Directory Service API which supports both a PUT and a POST as discussed in w3c/wot-discovery#160. I'm not convinced they're really any different.

I am not entirely convinced by the need to have a TD for the TDD

I share this view and I don't think the current approach is really working, particularly with regards to trying to model collections of resources. I have proposed #172 with some alternative approaches which may help by adding some directory-specific semantics. I'd also be fine with ditching the idea of using a Thing Description altogether and just defining the API in the prose of the WoT Discovery (or WoT Profile) specification, with an OpenAPI description as a machine-readable version.

I also think that the TDD is not a Thing

I agree, which I suspect is why shoehorning the Directory Service API into a Thing Description doesn't feel right.

However, a physical hub/gateway device is a Thing, and it would be nice to be able to provide a Thing Description which describes its capabilities (e.g. a "reboot" action) whilst also linking to a collection of other Things the gateway hosts. See w3c/wot-discovery#172 (comment) for ideas about how that could work.

the API is for now only focused on HTTP

If this were true then things would actually be simpler, but there now seem to be additional requirements that:

1. The API is protocol agnostic and can for example also fit within the limitations of MQTT
2. The API is convenient to consume from the existing non-normative scripting API

These requirements are complicating things further.

[egekorkan]

In case we do decide for a new op, this would be TD 2.0, deferring

[lu-zero]

I guess it is yet another item for the interaction affordance overhaul, explaining the two semantics will be interesting:

• write -> replaces the state as whole
• patch -> changes some parts of the state, potentially depending on the current state?