Re: [WoT IG] Proposals for potential work items of a WoT WG

Hello,

First, thank you for inviting me to participate in the F2F meeting in Sunnyvale. 

I’ve been working on some TDL and protocol binding examples for the lighting test case and have a general observation and question about the API discussion.

I think there may be at least two different definitions in use for what an API description is and what it does. 

On one hand, there is the definition of how a WoT server/servient exposes thing resources (events, actions, properties) to clients, with bindings to different M2M protocols like CoAP, MQTT, HTTP. Example modeling languages are WADL, RAML, Hydra. I’m focused mainly on REST APIs with hypermedia controls here, where there are resource paths, media types, status codes, etc. associated with the various affordances a thing exposes over a network protocol. The relevance to WoT is in mapping the protocol-independent actions, events, and properties to protocol-specific state machines and external (serialized) representations. This is the interface a WoT client would use to interact with a WoT server (and of course servient to servient). 

The other type of API is the definition of application software interfaces to a common client, like a web browser, with bindings to different programming languages. This API exposes a common internal representation to different programming languages. There is an analogy to the browser API exposed to scripts and web page controls, with different data models from different web sites rendered in a common DOM with well known API. I think this is the class of API that Web IDL belongs to. There will be a similar abstraction for the WoT scripting API; an internal common data model that is the functional equivalent of a DOM, (a TOMs?) and a set of programming language bindings to events, actions, properties, and discovery based on the WoT thing data model. 

The M2M side interface with protocol bindings to TDL will enable a common WoT client (servient) to interact with diverse types of things using hypermedia controls for stateless interaction, evolvability, interoperability, etc. For this interface I am looking at using JSON-LD and some similar constructs as Hydra but generalized for protocol bindings to CoAP, HTTP, and MQTT. The use of JSON-LD should allow easy reference and linkage from TDL.

Does this make sense? How are we distinguishing between the different level APIs? Protocol bindings and language bindings to a common thing model? Southbound (protocol) and northbound (Programming Language) interfaces to a common client library?

Best regards,

Michael


On Aug 12, 2015, at 3:32 AM, Hund, Johannes <johannes.hund@siemens.com> wrote:

> Dear Colleagues,
>  
> I agree with Kazuo-san that there is a great value in describing the API pattern in a way that it can be mapped onto various languages (C/C++, Java, Javascript, LUA, python etc.) as we will have very different domains and environments that will use the API.
>  
> W3C usually also does describe the browser APIs language-agnostic in webIDL:
>  
> http://www.w3.org/TR/WebIDL/
>  
>  
> best regards,
> Johannes
>  
> Von: Lynn, James (Fortify on Demand) [mailto:james.lynn@hp.com] 
> Gesendet: Dienstag, 11. August 2015 20:35
> An: kajimoto.kazuo@jp.panasonic.com; dsr@w3.org
> Cc: Heuer, Joerg; public-wot-ig@w3.org
> Betreff: RE: [WoT IG] Proposals for potential work items of a WoT WG
>  
> Kazuo-san,
>  
> Are you suggesting something similar to IDL?
> http://www.omg.org/spec/IDL35/
>  
> BR,
>  
> J Lynn
>  
> From: kajimoto.kazuo@jp.panasonic.com [mailto:kajimoto.kazuo@jp.panasonic.com] 
> Sent: Tuesday, August 11, 2015 1:42 AM
> To: dsr@w3.org
> Cc: Joerg.Heuer@siemens.com; public-wot-ig@w3.org; kajimoto.kazuo@jp.panasonic.com
> Subject: RE: [WoT IG] Proposals for potential work items of a WoT WG
>  
> Dave-san,
>  
> Thank you very much for adding items to be discussed in the wiki site.
>  
> I agree to take care of using terminology “API”. And I understand that it might be harder to standardize
> API across various languages.
>  
> But in
> “https://www.w3.org/WoT/IG/wiki/Proposals_for_WoT_WG_work_items#Proposal_Structure”
> the objective of WoT API, we’ve introduced terminology “Abstract WoT API”.
> This is some kind of classification of APIs and abstract description of functionality.
>  
> I think it is valuable to make consensus of such abstract API image to describe how the WoT servient
> works.
>  
> BR,
>  
> PS.
> Please enjoy your vacation ! J
> ----
> Kazuo Kajimoto
> Senior Councillor of Groupwide Software Strategy,
> Groupwide CTO Office
> kajimoto.kazuo@jp.panasonic.com
>  
>  
> From: Dave Raggett [mailto:dsr@w3.org] 
> Sent: Tuesday, August 11, 2015 3:46 AM
> To: Kajimoto, Kazuo (梶本 一夫)
> Cc: Joerg.Heuer@siemens.com; public-wot-ig@w3.org
> Subject: Re: [WoT IG] Proposals for potential work items of a WoT WG
>  
>  
> On 10 Aug 2015, at 04:51, <kajimoto.kazuo@jp.panasonic.com> <kajimoto.kazuo@jp.panasonic.com> wrote:
>  
> Dear Joerg-san and WoT IG members,
>  
> I strongly agree with Joerg-san’s proposal that listing up items for preparing WG first,
> before WG charter detail discussion.
>  
> I have risen to the challenge, see:
>  
>         https://www.w3.org/WoT/IG/wiki/Proposals_for_WoT_WG_work_items
>  
> 
>  
> I’m confident we could conclude abstract WoT API in spite of not only wide variety of
> description languages but also wide variety of implementation models such as “Web
> Centric”, “Smartphone Centric”, “Hub Centric” and “Cloud Centric” as described in attached
> PDF file.
>  
> Thanks for providing those slides.  All of the cases you depict are supported by the above proposals.
>  
> Note that when a web page running in a browser wants to access “things” on a server, the browser and the single origin security policy imposes some restrictions, e.g. the range of protocols is limited to those that browsers expose to web page scripts. Furthermore, the single origin security policy will require the same domain name as for the HTTP server used to download the web page.
>  
> In my implementation work, I used NodeJS to create a server that supports both HTTP and WebSockets specifically to address these restrictions. In principle, CORS headers could be used to enable the use of servers with separate domain names.  Something to explore in the future is the potential for using the data channel exposed by WebRTC. This would enable a web page on one browser to access things hosted by a web page on another browser.
>  
> There is an open source implementation of NodeJS for Android that makes it easy to implement a web of things hub/server on a smart phone or tablet. NodeJS also works well on high end microcontrollers such as the Raspberry Pi, which makes it easy to experiment with home hubs.
>  
> I think we should be careful with how we use the term WoT API.  This could be used for scripting APIs, e.g. as exposed to JavaScript or other scripting languages. It may also be used in an abstract sense to describe a messaging protocol.  I have been careful to limit my use of API in the scripting language API sense, and bindings to protocols for the messaging protocol sense.
>  
> Whilst it would be desirable to have the same scripting APIs on different programming languages and IoT platforms, I suspect that IoT platforms will have significant variations in their needs, and as a result, it may be harder to standardise WoT APIs across platforms. It is for this reason that I have not included APIs in the work items in the proposed charter.
>  
>  
> Best regards,
> —
>    Dave Raggett <dsr@w3.org>