RE: hello and some feedback

Somehow I missed your reply Martijn, sorry.

On 19 Aug 2014 at 14:39, Martijn Faassen wrote:
> On Tue, Aug 19, 2014 at 1:55 PM, Markus Lanthaler :
> [snip]
>>> I can't find examples of how a response actually points (deferences?)
>>> to its documentation; I only see examples with a context directly
>> 
>> It uses the same mechanism as discovery: an HTTP link header.
> 
> Aaah. I had expected there to be some kind of reference in it in the
> context. I was totally focused on the context here. But why is the
> context not used for this purpose? Why this new mechanism? I thought
> the context was the mechanism in JSON-LD to express things about the
> resource.

The context describes the *representation*, not the resource. It describes how short string tokens such as "name" in the JSON have to be interpreted. The Hydra ApiDocumentation describes things such as the operations supported by resources. So they serve quite different purposes.


> Aren't there now effectively two contexts?

There might be two contexts (one in the resource representation, one in the API documentation document), one, or none at all. A JSON-LD document doesn't require a context if all URLs are spelled out in the body of the document. This is called Expanded Document Form:

  http://www.w3.org/TR/json-ld/#expanded-document-form

The algorithm to transform an arbitrary JSON-LD document to expanded document form is described in detail in the JSON-LD API spec:

  http://www.w3.org/TR/json-ld-api/#expansion


> To write a hydra client it would need to examine the context *and* the
> HTTP link header in order to get the full information on how to deal
> with a resource, correct?

Correct


> [batch size]
>>>> 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).
>> 
>> It is possible, but it would be the server's job to tell you the URL instead
>> of having the client to construct those URLs.
> 
> I don't think I understand. Are you saying it is possible for a server
> to give the client a URL that instructs it to use a Prefer header for
> batch size?

No. I'm saying that if a client sends a request with a Prefer header, the server might respond with a redirect which then includes the page size in the URL. You can then pass that URL around.


> [snip]
>> or you embed this anonymous node (it's called a blank node) directly as follows:
>> 
>>   {
>>     "@context": "http://www.w3.org/ns/hydra/context.jsonld",
>>     "@id": "http://api.example.com/an-issue/comments?page=3",
>>     "@type": "PagedCollection",
>>     "changePageSize": {
>>       "@type": "IriTemplate",
>>       "template": "http://api.example.com/an-issue/comment{?page,itemsPerPage}",
>>       ...
>>     }
>>     ...
>>   }
> 
> Ah, yes, I was thinking that might be possible, but I got distracted
> by the discussion of the Link class and the TemplateLink class.
> Perhaps that's something that can be made more clear in the spec.

Sure. Do you have a concrete proposal to improve it?


 
>>> 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.
>> 
>> Does the above example clarify how it works?
> 
> Yes, somewhat.
> 
> JSON-LD is still gelling in my mind right now - I need to see where
> example 3 sits in a larger JSON object,

Typically it would either be in the vocabulary definition that defines your domain concepts or in the Hydra API documentation.


> and also how you could assign
> an iriTemplate an @id and then how you refer to that id again. I'm
> going to look some more at your references and browse the specs some
> more, then sleep on it.

It always the same. You would simply add an @id property:

  {
    "@id": "/my-iri-template",
    "@type": "hydra:IriTemplate",
    "template": "/users/{id}",
    ...
  }

I have to say though that I find that to be a bit confusing if the template is defined in a different document than the one where it is used as it is not immediately obvious that it is a IRI template:

   "search": "/my-iri-template"

But you can of course make that clearer by also explicitly including the type when referencing it:

   "search": { "@id": "/my-iri-template", "@type": "IriTemplate" }


> I'll have either better questions or better answers in the morning. :)

:-)


Cheers,
Markus


--
Markus Lanthaler
@markuslanthaler

Received on Thursday, 21 August 2014 15:01:14 UTC