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

> Isn't the browser a client?

Yes, sorry. I often use the word "client" for the (web) app that
consumes the API to distinguish between the app and the browser.
Sorry, for the confusion.

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

Well, the browser does that for the client (say: app), too. I'd
definitely say that the use sees and consumes the HTML document. Maybe
it doesn't look like source code for the user, because it is a
graphical representation rendered by the browser, but with some
imaginary you could also say that the client doesn't look at the
JSON-LD document, but some binary representation :)
For me it makes sense to say: What HTML is to the user is JSON to the
app client and HTTP header should be meaningful to the browser.

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

No, I don't mean that in some visually way. What I mean is that it is
beneficial to embed links directly into a resource. You get mostly
links with no templating (say: place "/users/1" and "users/2" inside
"users[0]" and "users[1]" instead of placing "/users/{id}" somewhere
in the root of the payload), you can use different links for similar
resources (DELETE "/users/1" but not "/users/2"), etc.

> Are you aware of the HydraConsole?

Yes. One of the things that drove me to this mailing list! :)

> If you already have a simple Web API, we could also discuss concretely how to convert it to Hydra together if you want.

I definitely would like to do that, but I think we still need some
weeks to work on our API to settle some things.

> Could you please formally join the Hydra W3C Community Group

Done! Already was in the middle of the process to do this, but got
distracted somehow.

Cheers and thank you all for the nice welcome,
Pipo

2014-07-10 14:18 GMT+02:00 Markus Lanthaler <markus.lanthaler@gmx.net>:
> 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?
>
>
>>> 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.
>
>
>>> 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.
>
>
>>> 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.
>
>
>> 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 Friday, 11 July 2014 07:54:28 UTC