Re: Express "go to specific page" for a collection

On Thu, Jul 10, 2014 at 2:18 PM, Markus Lanthaler
<markus.lanthaler@gmx.net> wrote:
> On 10 Jul 2014 at 09:45, Tomasz Pluskiewicz wrote:
>> On Thu, Jul 10, 2014 at 8:43 AM, Philipp wrote:
>>> With my "current" knowledge about HATEOAS I have the following philosophy:
>>> HTML is the best hypermedia format I know and our JSON hypermedia format
>>> should use the same principles.
>>
>> I've just discussed this with a colleague yesterday and my conclusion
>> is that HTML and Web API hypermedia differ in a fundamental yet subtle
>> way. HTML is a markup of the view while any JSON/XML/RDF/whatever that
>> client and server communicate with is tha data. And so the hypermedia
>> is move to another layer of applications.
>
> APIs typically don't care about the visual representation but other than that the principles are more or less the same. Tomasz, what do you mean by "hypermedia is moved to another layer"? From which layer to which layer?
>

With HTML the browser gets both the data+hypermedia controls and the
visual layout combined. With Web APIs the data is separated from the
view (the view could be something else than HTML). And with Hypermedia
API the hypermedia controls are moved from the view to the data.

>
>>> That said a user who browsers the web consumes the HTML document. A normal
>>> user doesn't look into HTTP headers.
>
> No, because the browser does that for the user. The normal user also doesn't look at the HTML source code as the browser handles that for him too.
>
>
>>> Likewise a client should gather all the
>>> data it needs from the JSON payload. There is no need for the client to
>>> consume HTTP headers - they're only really needed for the browser (e.g. for
>>> caching information).
>
> Isn't the browser a client?
>
>
>>> A user interacts with the HTML document via links (anchors or buttons). They
>>> know what they do, because they are labeled (e.g. "Buy now", "Click here to
>>> login", "Close this window"). A good JSON hypermedia format has a similar
>>> way to share vocabulary between server and client. Most formats seem to rely
>>> on "rel" and Link Types for this (e.g. "next", "prev", "index", "help",
>>> "edit"). I don't know if this is sufficient and I think this could be one of
>>> the major advantages of JSON-LD (- using schema.org for common vocabulary
>>> and Hydra for API-specific vocabulary). At least if I understand JSON-LD
>>> correctly.
>
> Yeah, that's the idea. Machines are really bad at understanding natural language. Thus we help them out by giving them unambiguous identifiers that identify certain concepts, i.e., URLs like http://schema.org/Person.
>
>
>>> Links in HTML documents are placed relative to their content (e.g. place a
>>> "share button" under every article in a blog - opposite to gathering "all"
>>> links at a central place). The JSON hypermedia format should do the same.
>
> Depends on what exactly you mean by "relative to their content". If you mean visually, then I have to disagree. IMO an API format should just express the raw data, not the visual representation thereof. There's no need to reinvent HTML in JSON IMO.
>
>
>>> Every resource has its own "links". (See the following example.)
>>>
>>> A form isn't much different from a common link: it just gathers some
>>> additional data and than you can follow "the link of the form" via a submit
>>> button. You can even specify the HTTP method which should be used. A JSON
>>> hypermedia format should include the same information: what data is needed
>>> to follow the link and what HTTP method should be used?
>
> Yeah. Though you have to distinguish between forms that change state (delete something, order something etc.) and forms that don't (search for something)-
>
>
>> I actually think that the term "hypermedia format" is not correct in
>> terms of Hydra. There already is a format and its called RDF. In
>> itself it is not enough for self-descriptive representations. However
>> Hydra is not a new format. Nor does it change RDF in any way. It is
>> merely an extension, which allows augmenting existing data with
>> description of hypermedia controls.
>
> RDF is a simple data model - even though most people don't believe that :-)
> JSON-LD is a serialization format for that data model.
> Hydra is a vocabulary defining concepts you need to realize a hypermedia-driven Web API.
>

Precisely. Hydra is still RDF, while other approaches all try to all
invent new formats.

>
>>> With these requirements in mind that is how we use JSON Hyper-Schema (basic
>>> example):
>
> The example can be found at
>   http://lists.w3.org/Archives/Public/public-hydra/2014Jul/0053.html
>
>> This is interesting. I haven't seen the JSON Hyper-Schema before and
>> it doesn't have the shortcomings I explained above in that the "core
>> representation" stays intact when adding hypermedia definition.
>
> The biggest difference is that links are completely detached and that everything is just described by string tokens and thus it is not obvious if the same string token (e.g., "description") means the same thing when found in a different API. This makes it much more difficult to write reusable code.
>

That is similarily true for other hypermedia formats. However JSON
Hyper-Schema is a step ahead, because it seems less intrusive and
allow annotating individual resources the way Phillip described.

>
>>> Yes, generating (or evaluating) forms is one of the benefits of this
>>> approach which we use. E.g. in a "create new user form" we could
>>> automatically set the "required" attribute on the input element for the user
>>> name.
>
> Are you aware of the HydraConsole? Check out the demo featuring a simple issue tracker at
>
>   http://bit.ly/hydra-api-demo
>
> and click on the "register_user" link. The "create new user form" is generated completely dynamically.
>
>
>>>> What are those benefits? Apart from the "go to specific page" feature,
>>>> what else is currently missing in Hydra in your opinion?
>>>
>>> I can't say what is missing in Hydra yet as I hadn't enough time to look
>>> deeply into Hydra. A "go to specific page" feature would be very easy with
>>> JSON Hyper-Schema: just add a new "link" object on the collection which has
>>> a schema definition that requires a "page" param with an int value. (The
>>> server could automatically include a "min" and "max" page, too. Very handy.)
>
> The only thing that is missing is a "page" property to be used as parameter. You would need to define that yourself... just as you have to do with JSON Hyper-Schema. If your application understands that property, you get exactly the same functionality.
>
>
>> Unlike next/prev page, which Hydra defines out of the box, there
>> probably won't be a goToSpecificPage property, because it requires the
>> use of a IriTemplate.
>
> Why is that bad? The "search" property also requires a IriTemplate. What we need to discuss is whether this feature is "popular enough" to be included in the core vocabulary.
>

I mean that in itself this property is incomplete. For real-world use
you need to create a subproperty and define an actual template and
mappings, right? And they will be specific to that on use case. But on
second though I see that such base template proeprties for common
relations do have their place.

I think the question is how much benefit is there for the client? What
will the client gain knowing that a given property, say
soccerApi:search, is subproperty of hydra:search? Or the hypothetical
hydra:goToSpecificPage?

>
>> However all the building blocks are there.
>>
>> Markus, please correct me here. Also I think that the vocabulary
>> documentation page is a bit lacking in this regard. I would add a
>> complete example of how a IriTemplate fits into a resource
>> representation.
>
> Yeah, the spec certainly has to be improved. The idea is to use an exemplary Web API (perhaps one managing events) to describe all the concepts. I will send out a couple more consensus calls to stabilize things and then, hopefully sometime in August, we will start to improve and perhaps reorganize (ISSUE-44 [2]) the spec.
>
>
>>> I hope you have a picture of what we want to achieve now :)
>
> Yeah, that helped to understand where you are coming from. I think most of what you need is already supported by Hydra. Don't hesitate to ask questions. The spec isn't fully up to date so in most cases it will be more productive to simply ask. If you already have a simple Web API, we could also discuss concretely how to convert it to Hydra together if you want.
>
>
>>> Btw, I'm coming from Leipzig. I saw that one person in the Hydra group is
>>> associated with the university of Leipzig. What a coincidence! We're
>>> literally neighbors :)
>
> Cool! This brings me to another point. Could you please formally join the Hydra W3C Community Group at
>
>   http://www.w3.org/community/hydra/
>
> This is important to ensure that we don't run into any IPR issues when we put Hydra on the Recommendation track at W3C.
>
>
> Thanks,
> Markus
>
>
> [1] https://github.com/HydraCG/Specifications/issues/44
>
>
>
> --
> Markus Lanthaler
> @markuslanthaler
>
>
>

Received on Thursday, 10 July 2014 12:45:07 UTC