Re: Home Documents for HTTP APIs

Hi Melvin,

>  Of course, an HTTP API might use any format to do so; however, there
>  are advantages to having a standard home document format.  This
>  specification suggests one for consideration, using the JSON format
>  [RFC4627].

How does the idea of a home document compare to API descriptions?

Right now, I’m not sure about the added value of the home document, compared to regular hypermedia links.
If we consider the example at http://tools.ietf.org/html/draft-nottingham-json-home-00#page-4,
we can see that much of the information therein could be available as links on a regular resource.
An index resource (in HTML/Atom/JSON/… representation) could link to the widget index,
and that index could link to the individual widgets.
Also, the “allow” and “representations” information can be part of the headers.

API descriptions, on the other hand, could offer additional semantics to machines
that would help them understand what the API provides.
For instance, we are working on RESTdesc (http://restdesc.org),
which explains the functionality of an API to machine clients.
Concretely, the index document could link to a description document,
and this document would explain what a widget is and what happens when you POST to it.

In my opinion, this provides more added value,
since functionality is not discoverable by the other HTTP mechanisms,
but the links in the proposed home document are.

Best regards,

Ruben

Received on Thursday, 24 May 2012 07:31:46 UTC