hello and some feedback

Hi there,

I'm Martijn Faassen, and I've been interested in RESTful APIs for a
while. It always bothers me that people can use the word "REST" and
ignore links. I work on a Python web framework called Morepath that
has more knowledge about linking than usual. I'm considering building
a framework on top of it that knows about JSON-LD and Hydra.

I have been browsing through the Hydra Core Vocabulary draft spec and
I have some pieces of feedback so far which I thought I'd share just
in case they hadn't come up yet:

Section 4.3, discovering a Hydra-powered web API

* In example 11, the Content-Type is 'application/ld+json'. Is this
not a bit misleading? Isn't www.example.com not more likely to deliver
HTML, so content type would be text/html? The whole point is that it
is not a hydra resource itself but a page in which you can discover
the entry point to the Hydra resources, right?

* it is a bit surprising to me that it's a link to the docs instead of
the main entry point of the application. I think it's in part because
the word "documentation" doesn't imply something machine-readable
normally, but here it's very explicitly machine readable and you're
supposed to look in it for the entry point.

* I myself would've expected a link to the entry point, and this can
then contain a reference to the docs. What are the reasons for not
having it this way around?

Section 5.1, collections:

* Instead of explicit paging, another way to represent collections is
to give it some kind of offset and limit (analogous to a SQL query).
The server generates a 'previous' and 'next' links; first and last
page might not be there. This also allows the client to potentially
request something with a larger limit than a server-determined page
size. The server should of course have a maximum limit too. The
advantage of this is that the client can control the page size, which
can be useful if it represents a batching UI.

* in this case it becomes useful for the client to know about what
parameters may be sent to control offset and limit. I think this
relates to 5.2. It'd be interesting to explore how collections and
templated links work together.

Thank you for your attention!

Regards,

Martijn

Received on Monday, 18 August 2014 12:27:00 UTC