Re: HTML as a format for REST APIs

May I suggest that JSON-LD / Semantic Web definitions is probably a
stronger route to go. If you need to embed in HTML, this can be serialized
with RFDa, but the real issue is how the underlying data is defined, not
it's serialization.

I've been thinking and writing for the last few months about how these
could be used in a Semantic Web context, with REST & HATEOAS. Here's two
slideshows:

-
http://www.slideshare.net/dpjanes/building-blocks-for-the-internet-of-things-home
-
http://www.slideshare.net/dpjanes/2013-07-connecting-the-internet-of-things-to-the-semantic-web

Some of my thinking has evolved since then, but this does get you to

GET /devices/lights/0
{

    "@context" : "/definitions/light,
    "on" : true,
    "brightness" : 0.5,
    "color" : "#FFFFFF"

}
More links here, for the thinking behind these things:

- https://plus.google.com/communities/108112460238486371606 (REST
Interfaces for the IoT)
- http://imadeit.davidjanes.com/ (my blog - mostly about the IoT but not
specific )

Regards,
David



On Mon, Sep 16, 2013 at 5:47 AM, Dominique Hazael-Massieux <dom@w3.org>wrote:

> 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
>
>
>
>