[Charter]: include both Scripting and REST API

[zolkis]

I would like to ask the group whether could we replace "Scripting API" occurrences in the charter with "Scripting and REST API".

Based on my experience with IoT so far, I believe we can make a better Scripting API when thinking about a REST API as well.

So it would be nice if the charter allowed to work on specifications to both a Scripting and a REST API.

[draggett]

I agree that REST is important, but it is not the only approach we need to consider. For example, how does it apply to asynchronous messaging protocols like Web sockets, topic based pub/sub protocols, and streaming protocols including Server Sent Events? For this reason, I would prefer to avoid giving REST undue emphasis.

[zolkis]

Of course it would not be the only deliverable - the point was to allow work on a REST spec in the WG.

[domguinard]

It does make a lot of sense to add "Scripting and REST API". Starting with REST is a good approach to design a good scripting API indeed. Also, proposing a REST API would address the concerns that were raised by some ACs when approving the charter. EVRYTHNG would also happily support the design of such as REST spec.

[draggett]

Note that W3C already has a standard API for REST as part of the open Wen platform, so you should provide an indication of why a new API is needed.

[zolkis]

That's a good point. Which one did you mean? I have found these: https://www.w3.org/2012/ldp/charter (expired), general spec here: https://www.w3.org/TR/ldp/ https://www.w3.org/community/hydra/ (http://www.hydra-cg.com/spec/latest/core/ )

The above are good input for WoT REST. The latter is a special application, with specific use cases (which are shared with the WoT Scripting API). We can't expect to work on a WoT REST API in that WG/CG, right? For instance Thing Descriptions are not discussed there, either.

We can discuss and then embrace, drop or transfer REST API work, but the point is, can we arrive to this in the WoT WG, and does the WoT WG charter allow working on that.

[zubairhamed]

If you don't mind me asking, which Open Web Platforms did you mean?

I was halfway implementing this before encountering the one you guys are working on, so i put it on a pause for now..

https://www.w3.org/Submission/2015/SUBM-wot-model-20150824/

Z

[mkovatsc]

Please clarify what you exactly mean when talking about a "REST API". I do not fully understand on what terms you are even discussing:

0) Just using HTTP does not give you REST. 1) When using a RESTful protocol and the TD, you automatically end up with a REST API. 2) Defining how to name resources, how requests must be created, and what exact responses to expect has nothing to do with REST. 3) The Scripting API is at a different level than the network ("REST") API. The Scripting API ensures that WoT application code becomes portable and will execute in any WoT runtime. It standardizes how messages can be sent and received, and how information from representation formats ends up in accessible program variables.

[draggett]

@zubairhamed - I was thinking mainly about the very widely used XMLHttpRequest API.

[zubairhamed]

@draggett That's a pretty specific JavaScript API for browsers (aka Ajax) which isn't applicable to other languages/platforms. I would expect a REST API to be a contract between so-called Servients, servers and clients i wound imagine.

In my mind, a Scripting API could be this tiny snippets of code which are used to handle various events, validation, business logic etc (ala Lambda/Serverless apps)

[zolkis]

@mkovatsc I agree with all your points, but I don't see how do they relate to this discussion. We need to specify how are we using REST for our use cases. That work is better carried out in the WoT WG. I don't understand what is not clear about the request. Also, the proposal @domguinard mentioned defines the context quite well: https://www.w3.org/Submission/2015/SUBM-wot-model-20150824/

I try to understand/reformulate your concern: are you saying WoT does not need to standardize any REST API at all, because a Scripting API is a better abstraction?

If that is the concern, then we have a divergent view on this in the group. Some members say REST API is enough and they are not even interested in Scripting API, some say Scripting API is enough and let's not do REST at all, some (like me) say we need both.

What about letting people choose what they need? Is it a problem if the WG would be working on both a REST and a Scripting API?

[draggett]

Another perspective on this is that the charter has been through the AC Review, and we've addressed the reviewer's comments with clarifications on scope and priorities. If we were to make substantive changes such as identifying a new work item, we might need to repeat the AC Review which would introduce a considerable delay into starting the Working Group. If the current wording is adequate to permit work on a REST API then I would prefer to stick with that wording and leave the interpretation to the Working Group once it is up and running. If the current wording is judged as ruling such work as out of scope, then we will indeed need to repeat the AC Review, assuming there is a broad consensus on introducing such a change of scope.

[zolkis]

If the current wording is adequate to permit work on a REST API then I would prefer to stick with that wording and leave the interpretation to the Working Group once it is up and running.

I am totally fine with this. I just wanted to make sure the WG is allowed to work on a REST API as well. I thought the proposed change would be a small clarification in the charter that would not require full re-review. But if the intent is already covered, I am fine with the current formulation.

Just to make it sure: we'd actually like to discuss and take @domguinard 's proposal further in the WG. If it comes out short, we can drop it later. If it gets somewhere, IMHO it would be a useful addition to WoT. As for the practicalities of that work, a task force would be good - similar to the Scripting API task force. Would that be OK with the present formulation of the charter?

[benfrancis]

@domguinard wrote:

EVRYTHNG would also happily support the design of such as REST spec.

Mozilla would also support a REST API as a deliverable for the WoT Working Group charter and would like to collaborate with other interested parties on defining this. We have started work on a potential member submission from Mozilla to help make this proposed direction more concrete. This will have a lot in common with the previous Web Thing Model member submission.

We would actually go further than this and suggest that the charter should include a REST API instead of a language agnostic Scripting API.

@draggett wrote:

how does it apply to asynchronous messaging protocols like Web sockets, topic based pub/sub protocols, and streaming protocols including Server Sent Events?

CoAP includes a notify mechanism and an HTTP connection can be upgraded to a WebSocket connection to satisfy the "subscription" type use cases. HTTP/2 also provides a potential solution for these use cases and there are fallbacks available in HTTP.

I was thinking mainly about the very widely used XMLHttpRequest API

I think you may have a misunderstanding about what members mean by a REST API. I do not mean a scripting API to call a REST API (e.g. XMLHttpRequest in JavaScript), I mean a formalising a REST API you call over the network (consisting of GET, PUT, POST and DELETE requests). This may be closely connected with the Thing Description which can use a HATEOS approach to enable the discovery of additional resources which make up the REST API from a single starting URL.

Another perspective on this is that the charter has been through the AC Review, and we've addressed the reviewer's comments with clarifications on scope and priorities. If we were to make substantive changes such as identifying a new work item, we might need to repeat the AC Review which would introduce a considerable delay into starting the Working Group.

With respect I don't think reviewers comments have been addressed (specifically the objections from Mozilla and Google), but Mozilla will follow up on this formally. In my opinion the risk of fragmenting the group by failing to sufficiently address feedback is more significant than the risk of delaying the approval of the charter.

[zolkis]

@benfrancis

We would actually go further than this and suggest that the charter should include a REST API instead of a language agnostic Scripting API.

When you say "language agnostic", I also find that shooting too high, and actually paralyzing work on each concrete language. Focusing on a few concrete languages would be much more clear.

However, IMHO dropping the scripting API is not realistic. AFAIK all IoT organizations produce APIs. In practice, IMHO we have the following options:

1. work on both a REST and a scripting API in the WoT WG (whether charter change is needed for that or not)
2. create a separate WG or CG on WoT REST API and related stuff.

I don't think creating a separate WG or CG for the scripting API would make much sense so I didn't list that as an option. I agree with the opinion that TD should be the main focus of the WG.

[mkovatsc]

@zolkis No, I definitely did NOT say "WoT does not need to standardize any REST API".

My main concern is that many people don't know what REST actually is, use it as a synonym for an HTTP API, and want fixed resource paths and messages, which do not give you any of the actual benefits of REST.

Putting the REST API next to the Scripting API or in the same deliverable does not make sense. I already tried to explain that they are at different levels.

The REST API fits under the Thing Description, which is also why it is the center piece: Our interaction model already fulfills the "client-server" and "uniform interface constraint". In the design of Actions we have to respect "statelessness". The envisioned architecture gives us "layered system". "Cache" will be tricky for non-RESTful protocols where we cannot alter the payload (existing platforms), but we could give cache-control information in the TD. "Code-on-demand" is enabled through the scripting API.

What you actually have to agree on to get a REST API is the vocabulary to select links and forms, and a set of hypermedia formats or vocabulary to enhance generic formats. This work is done in the normative TD deliverable. Agreement on protocols is done in the protocol bindings/mappings.

[mkovatsc]

What about letting people choose what they need? Is it a problem if the WG would be working on both a REST and a Scripting API?

Yes, that is exactly the intention and why we call it WoT building blocks.

Companies can use just the TD to describe their REST API in terms of links, forms, relation types, representation formats, and schemas for generic formats.

All the companies that want to have a standard way to implement portable application logic that interacts with TD-described interfaces can use the Scripting API.

Companies can pick only the protocol binding/mapping they need for their platform or use the templates to add a new one if their protocol is not included.

[mkovatsc]

create a separate WG or CG on WoT REST API and related stuff

Based on this radical move, I would like to ask again, how you define "REST API".

[zolkis]

The REST API fits under the Thing Description, which is also why it is the center piece

Thanks for putting it this way, it is only now that I got what you meant... Perhaps we'd need to improve on communicating this clearly in the right context. A FAQ and rationale history is in order.

Then you'd say people who want to work on REST APIs should work in fact on TD?

If so, then I guess charter change is not needed. However, IMHO the WoT WG will still need to make a report/recommendation on how exactly to do REST with Things. It's not enough the mention the theoretical possibility to use whatever interactions with the TD. Examples, use cases, recommendations etc are needed.

If that's already taken as granted based on TD work, then please make sure to explicitly document it and put e.g. Dom's contribution in context.

Companies can use just the TD to describe their REST API in terms of links, forms, relation types, representation formats, and schemas for generic formats.

Certainly this isn't far from RAML definitions, and suddenly Dave's converter tool fits better in the picture.

create a separate WG or CG on WoT REST API and related stuff

To be clear, I am not interested in a separate CG/WG for REST, as I'd like to do the work in the WoT WG, mainly on scripting, but REST (and it seems TD) as well.

Putting the REST API next to the Scripting API or in the same deliverable does not make sense. I already tried to explain that they are at different levels.

I know they are at different level. What I say is they share use cases and one end using scripting API should be interoperable with a REST-only client. How that is achieved needs some work, whether in the TD context or in its own.

[danbri]

One aside about REST. It is typically associated with with HTTP(S) as underlying protocol, but there is no deep reason for message patterns analogous to HTTP's "GET" existing in other protocol environments....

[mjkoster]

"What you actually have to agree on to get a REST API is the vocabulary to select links and forms, and a set of hypermedia formats or vocabulary to enhance generic formats. This work is done in the normative TD deliverable. Agreement on protocols is done in the protocol bindings/mappings."

This is really the essence of REST + hypermedia, which is the power of web architecture. Links and forms are the low level interaction constructs for, respectively, properties and actions, and a protocol binding to well defined CRUD+async notification abstraction, allows HTTP, CoAP, and pubsub to be used as alternate transfer layer implementations.

Hypermedia links and forms decouple the abstract interactions from the protocol, and allows us to build a much more evolvable system than one which uses fixed URI templates and function mapping.

It seems like the current scope as defined in the charter documents allows this. We could easily add some paragraphs to further describe the deliverables in terms of specific protocols and mappings, e.g. REST, hyperlinks, action forms, and notification constructs. What it comes down to is something analogous to HTML, but targeted to machine interactions, semantic interoperability, and mapping to multiple transfer layer protocols.

[h0ru5]

Copying my comment from the mailing list (we should consider some way to sync those two discussions):

Regarding REST API and Scripting API: we had a Babylonian confusion everytime somebody said API. - Do they mean the scripting API or the Web-API/REST-API/Protocol Binding? IMHO we always have been targeting to define a "narrow-waist" model (events, properties, actions, ...)and serialize it (as the TD), access it from scripts and map it to resources so we can define REST-bindings and easily adopt to various protocols by mapping the REST primitives.

I think the question in the room is how to map the model to RESTful resources and if you can do it vice versa ?

One approach is to define how the uris should look like plus what payloads are expected and returned etc. as it is done in the submission from COMPOSE/EVERYTHNG.

I like the approach of the submission and see the value, specifically if you have a green field, you know exact and concrete how to design your resources. I think we might need more that this (adding to it and complementing), if we want to use the approach also for the "brown field", such as existing REST APIs, devices, silos, other standards such as OCF etc. Specifically, I would avoid to hardcode the uri templates in the client.

My suggestion would be to have a way to provide links between the uris and define a handful of relations you need to know (action, property,...), as it is done with the HATEOAS principle. Then we can use thing description as a point where you find all links, like an equivalent to "index.html" (or e.g. the directory listing index from apache).

The delta to the current form is in my opinion:

• No hard requirement of HTTP, but a focus on defining resource structure and payloads, like OCF did with CRUDN + types etc. That way we can use also use e.g. CoAP etc.
• specify a way to express links (e.g. based on are approaches like HAL or JSON hyperschema)
• We need a way to provide a link list/map that allow the client to use existing resource structures using the same model , e.g. if there is a REST API that cannot be changed (legacy or a domain standard) - this could be the TD

This still keeps the client very straightforward, it just has to get a link from the data by its relation type and use .

This will work with both "Greenfield" and "brownfield" cases

[draggett]

The thing description is a contract between application developers and platform developers, and should be kept as clean as possible to minimise the information an application developer has to have about particular platforms. My OCF demo shows that the REST APIs can be generated from thing descriptions by code that knows about both thing descriptions and the specifics for a given RESTful platform like OCF. In this case, the thing description needed to include the OCF resource identifier, and whether a given property is optional or read-only.

My streaming demo and use cases show that where data is streamed as blocks of successive values, that apart from generic information like the sample rate and latency, there is no need for the thing description to go into the details, which can be left to the platform. To interoperate with another platform, you do need to have a matching platform driver, but this is transparent to the applications. I thus envisage drivers for OCF, oneM2M, Bluetooth GATT and so forth, and look forward to developing the corresponding proof of concept demos, based upon use cases for each such platform, where the aim is to establish each platform's minimal metadata requirements for thing descriptions.

Whilst I recognise the importance of the REST pattern, the details of how it applies is the responsibility of the platform developers that will design and implement the above drivers. The business value of standardising the building blocks for drivers is considerably less than that for the contract between application developers and platform developers, given that we expect a many to one relationship between the two sets of people. In other words each driver will be used by a great many applications.

[zolkis]

@draggett

I find your arguments convincing (after @mkovatsc enlightened me about the stance WoT has accepted). However, for the sake of completeness I would like to point out this is based on a postulate the group seems to have accepted by majority (with reasons that are not easy to find by newcomers), but other viewpoints are also present in the group.

So the postulate seems to be that "application" is defined by a script (using the Scripting API and TD) and RESTful interactions belong to the "platform" (implementation of the scripting API/TD). I think everything else stems from this assumption/architecture choice. This is a generalistic view.

From another viewpoint, application is whatever is able to work with a Thing (TD) with a minimum set of RESTful interactions (that is considered the lowest layer where WoT could be defined/generalized), whether it is actually done through "drivers", or "platform" etc doesn't matter. Mozilla seems to prefer this view, saying this is all that is needed, and a scripting API can be defined if the TD and RESTful interactions are defined (which is the opposite argument from the generalistic view). This is a minimalist view and even tries to 'occam away' scripting.

To keep this together, a layered approach is indeed desirable, as minimalists could implement WoT at a lower layer TD/REST (and we shall see if it's feasible to formulate it for wide interoperability) and all the others could use TD/Scripting.

At the moment there seems to be a consensus in the IG (except at least Mozilla) about how to handle Scripting API/TD relationship with RESTful (recommendations). We have shortly discussed this topic in today's Scripting TF call, and the summary can be pasted here as well.

[zolkis]

Closing this now, as it turned out that the current charter allows work on REST related recommendations.