RE: hello and some feedback

Hi Martijn,

And welcome on board :-)

On 18 Aug 2014 at 10:25, Martijn Faassen wrote:
> 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.

Great. If you have a couple of minutes, could you please briefly describe in what regards your framework is different from others? In any case, please keep us posted on your progress.


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

Good point. While it is not wrong, it is indeed misleading. I just fixed it:

https://github.com/HydraCG/Specifications/commit/4e9c04034b331805b05f30f3f281a7b63bfcdb9d


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

The entry point is an important aspect of an API which means it should be included in the documentation. Thus, if we would link to the entry point instead of the API Documentation, we would need to define two HTTP Link headers: one to point to the entry point and one to point to the API documentation. By always pointing to the API documentation we just need to define one. What would be improved if we would link to the entry point instead?


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

Yeah, that would be possible as well. We might address this at a later point if it turns out to be important. There are multiple ways we could address it.


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

Indeed. The most straightforward solution would be to return a templated IRI to access a specific page directly. Alternatives would be things like a Prefer header (for page size). Overall, I think most of this can be achieved (or worked around) quite easily client side. We discussed this already a while ago and couldn't really find a compelling use case which would require offset. If you have one, let us know.


Thanks,
Markus


--
Markus Lanthaler
@markuslanthaler

Received on Monday, 18 August 2014 22:18:35 UTC