Re: hello and some feedback

Hey,

Thanks for the welcome! I hope you'll bear with me; below some of my
lack of experience with JSON-LD will clearly be showing. :)

On Tue, Aug 19, 2014 at 12:18 AM, Markus Lanthaler
<markus.lanthaler@gmx.net> wrote:
> 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?

I have a lot of words here:

http://morepath.readthedocs.org/en/latest/compared.html

but that mostly relates to Python web frameworks and it's rather long.
So briefly:

I think there are two main points where Morepath is different:

Lots of built-in facilities for reusing code in various ways; both
fine-grained and course-grained facilities for reusing views and
applications, both
by doing inheritance and composition. The main relevance here would be
that you can easily compose JSON in a decoupled way. ("give me the
JSON
for this object and put it inside this other JSON").

The other difference is that Morepath is a routing framework that can
construct links to objects.

Morepath is a routing framework, so you can say for a route:

/issues/{issue_id}

how that is resolved to a representation, i.e. JSON.

But while typical routing frameworks do it in one step, that for
instance does a database query for a model, and then create a JSON
representation for that
model all in one function, Morepath breaks this in two functions:

* getting an object (instance of a model class) for a path

* making a representation for that object

This definition structure also allows you to create links to any known
objects by just saying "request.link(model)' without having to know
what
the model is or how a path to it is constructed -- that information is
retrieved from the routing information. This allows decoupling and
easy changing of the
route map. It also allows the server to very easily support REST by
letting it construct links and send them back.

A nice feature is that Morepath construct URL parameters (?foo=bar) in
links that way as well, so that if you have an object that represents
a query or a batch and you link to it, it can create a link with
parameters in it.

Sorry for the length, hopefully that was brief enough. :)

[misleading content-type]
> Good point. While it is not wrong, it is indeed misleading. I just fixed it:
>
> https://github.com/HydraCG/Specifications/commit/4e9c04034b331805b05f30f3f281a7b63bfcdb9d

Thanks, I think this will help comprehension, as reading the json-ld
content type there made me worry I was missing something.

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

I had thought you wouldn't need to define two headers, as you'd get to
the documentation from the entry point itself. But I'm trying to find
that back in the
specification, and while it says:

"Please note that in most cases the entry point will already be known
to the client. Thus, the discovery of the API documentation using HTTP
Link Headers is typically not necessary as the concepts used in
responses from the API will dereference to their documentation."

I can't find examples of how a response actually points (deferences?)
to its documentation; I only see examples with a context directly
pointing to the hydra vocabulary, not to an application-specific
documentation. I must be missing something or maybe I'm misreading
that line.

If I'm not misreading that line, it would be good to follow it up with
an example of how a response in the end points to its documentation.

[alternative kind of batching for collections]

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

I think often you'll see collections that support some kind of query
and a kind of batching at the same time. I think it would be useful to
describe such a combined collection. This because my struggles below
show that I actually have no idea how to describe that kind of
collection. :)

I'd also be interested in seeing examples describing other
interactions with the collection, such as adding. One operation I'm
curious about is 'batch deletion'; deleting multiple items from a
collection is often done more efficiently by sending a whole bunch of
ids directly to the server and having the server delete them as
opposed to issuing multiple delete requests. Though perhaps this isn't
great REST design; I'm not sure.

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

I myself really don't like using headers for this, as it makes it
impossible to pass around a URL to a particular batch (or generate
one, which I'm doing in Morepath).

I realized that since the structure of the IRIs for id and firstPage
and nextPage are opaque to the client, I can already accomplish
sending back id IRIs with '&offset=10&limit=20' URL parameters instead
of 'page' and still be Hydra. Correct?

In relation to this I'm trying to see how I use IRI templates, but I'm
having trouble figuring it out. I can construct something like this:

{
  "@type": "IriTemplate",
  "template": "http://api.example.com/an-issue/comment{?page,itemsPerPage}",
  ...
}

I'm at a loss on how I should refer to it. My lack of experience with
JSON-LD is showing. How would I state that a new property
"changePageSize" in Example 14 should be a templated link using this?
Could I also express this about the @id in example 14?

If itemsPerPage is not deemed important, I think I'd have the same
issues if I were to combine a (batched) collection with a query API
using URL parameters.

I'm having trouble seeing how example 3 (where a IRI is identified as
a link) fits into a larger example, and I think I need something like
example 3 for a templated link.

By the way, how can example 16 be the extracted definition of Hydra's
search property, but the context itself is the hydra vocabulary? Isn't
this definition *part* of the hydra vocabulary?

Regards,

Martijn

Received on Tuesday, 19 August 2014 09:56:23 UTC