ΑΠ: HTML as a format for REST APIs

Interesting resources you provide! 

Thanks for this.

Kostas

----- Αρχικό μήνυμα -----
Από: "Dominique Hazael-Massieux" <dom@w3.org>
Στάλθηκε: ‎16/‎9/‎2013 12:47 μμ
Προς: "public-wot@w3.org" <public-wot@w3.org>
Θέμα: HTML as a format for REST APIs

Hi,

As has been discussed by many authors, REST as an architectural style
feels like a good fit for the Web of Things:
* it defines an approach that can be used across APIs, not a specific
API
* it gives a lot of freedom to develop specific APIs which matches well
the heterogeneity of the "things" market
* it makes it reasonably easy for a client to discover the API instead
of having to know it in advance
* it integrates naturally with existing infrastructure (HTTP as a
protocol, easy interaction with Web browsers)

(there are also cases where it's less clear how to make it fit: server
push based interactions, bidirectional communications for instance)

Part of the REST contract is that clients need to know one of the
formats that the server exposes, and to determine the associated
semantics (e.g. at the very least linking semantics).

More often that note, these formats are ad-hoc ones based on JSON or XML
structures.

One format that is often overlooked an API format is HTML itself; there
is nevertheless a (growing?) movement to explore HTML in this space; see
for instance:
http://codeartisan.blogspot.fr/2012/07/using-html-as-media-type-for-your-api.html

This highlights that HTML has a number of elements that can be used to
denote traditional structures (arrays, associative arrays, sets,
groups), has "native" support for linking (again, a critical component
in REST/HATEAOS), and a number of nice additional features (media
attachment for instance); it also can be used to integrate more semantic
annotations (e.g. via RDFa).

Even more interesting in the context of service discovery (as needed for
the Web of Things), HTML Forms provide a very useful entry point to
describe services, as described in:
http://codebetter.com/glennblock/2011/05/09/hypermedia-and-forms/

To illustrate this, one could easily declare that a temperature service
is available at a given end point with the following markup
        <form action='/sensors/temperature' method='get'>
          <!-- the service can be called via GET and doesn't take any
        parameter -->
        </form> 
(provided this would get completed with additional semantics that is
about temperature)
or declare that one can subscribe to alerts when the temperate gets
above a given value with the following markup
    <form action='/sensors/temperature/watch' method='post'>
       <!-- the service is available via post -->
       <input type='number' min='0' max='373' name='threshold'
required='required'>
       <!-- takes a required param that is a number between 0 and 373
-->
       <input type='url' required='required' name='callback'>
       <!-- takes a required param that is an URL -->
    </form>
(again this would need to be completed with additional semantics to
denote "subscription", "threshold", and "callback")

I wonder if anyone has looked into how well this approach would fit in a
Web of Things world?

Dom