Re: RDF APIs should describe their responses

Thanks Ruben, nice timing

On Tue, Oct 06, 2015 at 02:12:06PM +0200, Ruben Verborgh wrote:
> [...]
> I think servers should also describe API responses to clients,
> similar to how websites for people contain text and links
> that describe much more than just the raw data itself.
> And RDF graphs offer a handy way to combine data
> with context and controls in a single response.
> This would enable clients to do more with an API.
> 
> I've sketched such a solution in more detail here:
> http://ruben.verborgh.org/blog/2015/10/06/turtles-all-the-way-down/
> Your feedback and thoughts are most welcome.

A few hours before reading your post, I announced a talk about REST at
my workplace, scheduled for next week. I read Fielding's dissertation to
figure out the architectural constraints imposed by REST. Furthermore, a
coworker pointed me to HAL[1] (JSON Hypertext Application Language).
While HAL approaches the "Hyerpmedia as the engine of application
state"-constraint, it falls short when it comes to self-descriptive
messages.  Take the following example from [1]:

   {
     "_links": {
       "self": { "href": "/orders/523" },
       "warehouse": { "href": "/warehouse/56" },
       "invoice": { "href": "/invoices/873" }
     },
     "currency": "USD",
     "status": "shipped",
     "total": 10.20
   }

Even for a human, this is not self-descriptive at all. During my talk, I
wanted to make a better suggestion using RDF. Thanks to you, I won't
have to work it out on my own. :-)

I believe, to realize a REST interface targetted at machine consumption,
both, the vocabulary used (currency, status, etc.) and the controls need
to be described in a machine-readable form. RDF is perfect to describe
the vocabulary and your solution allows mixing data and controls. I
think I am now much closer to undertanding REST and actually
implementing a REST interface in a real-life application. So, thanks for
your work.

Greetings
Urs

[1]: https://tools.ietf.org/html/draft-kelly-json-hal-07

Received on Wednesday, 7 October 2015 22:17:50 UTC