[badbotty]

Have you looked into JSON-ld? Sure it is an extension of json but it has a formal specification which solves all the problems you have with your json examples, specifically the out-of-band issue you have with your json and how to link to other things. FWIW I maintain a API and frontend which use JSON-ld and has the backend passing the information I need to render forms based of backend permissions like you are describing.

What your html isn't doing for me is give proper type information. Should I look for the text "Status: x" in some div to find the status, and how is this better than having "status" as a key in some json object? I would not enjoy developing a consumer which had to interface with an api nesting data in divs.

[brabel]

> What your html isn't doing for me is give proper type information. Should I look for the text "Status: x" in some div to find the status,

Oh wow, you seem to have come out of reading this blog post still extremely confused.

In HATEOAS, the client doesn't care at all about whether the page contains a "status". It displays the hypermedia the way it is given without knowing the semantics at all - that's what makes it de-coupled from the server. It only knows the semantics of the hypermedia, in this case HTML.

In cases where you want a single-purpose client that can automatically take action depending on your domain's concepts (like account status) you simply can't use HATEOAS, go with RPC, which is a much better choice, or, as most people today are doing, stateless JSON over HTTP (which is not REST as most developers today seem to believe).

[badbotty]

> Oh wow, you seem to have come out of reading this blog post still extremely confused.

Yea, guilty of not reading the article properly sorry. I now get what you are saying about not using the status to drive what forms appear in UI / actions can be performed. Using JSON-ld you might use the https://schema.org/potentialAction property to describe what actions the resources allows which provides the equivalent information as the HTML form tag.

After reading Roy Fielding's blog a bit I do find my understanding of REST to be lacking. My reading of the principles agrees with your statement: "It displays the hypermedia without knowing semantics at all" but then he seems to also endorse RDF and N3 which are more like JSON-ld from my understanding and I'm not sure how they cater to display purposes.

> When representations are provided in hypertext form with typed relations (using microformats of HTML, RDF in N3 or XML, or even SVG), then automated agents can traverse these applications almost as well as any human. There are plenty of examples in the linked data communities. More important to me is that the same design reflects good human-Web design, and thus we can design the protocols to support both machine and human-driven applications by following the same architectural style.

https://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypert...

[brabel]

RDF, JSON-LD and other "structured" formats try to allow clients to gain a certain understanding of what the data means... it's easy to understand that when you look at HTML's semantic tags [1], which let the browser and other clients know, e.g. what's the "main" section and what's just an "aside"... and structured data provided by RDF, Microdata [2] and JSON-LD (which were all the rage in the never-realized Web 2.0), which you can embed in the HTML itself in order to provide lots of metadata information to the client about the data in your web page.

Today, these are actually used by, for example, search engines [3] to display data in a structured manner on searches!

Unfortunately, I don't know of many other "creative" usages of this metadata, but I imagine there could be many... HATEOAS is IMHO still ahead of our time... I do expect that, at some point, it will be really beneficial to have clients that can have a good understanding of the information is shows to users, and one day it will suddently became the next big thing (again).

[1] https://developer.mozilla.org/en-US/docs/Glossary/Semantics#...

[2] https://html.spec.whatwg.org/multipage/#toc-microdata

[3] https://developers.google.com/search/docs/advanced/structure...

[simiones]

> In HATEOAS, the client doesn't care at all about whether the page contains a "status". It displays the hypermedia the way it is given without knowing the semantics at all - that's what makes it de-coupled from the server. It only knows the semantics of the hypermedia, in this case HTML.

This is not exactly what the REST thesis advocates for. You can absolutely create a true REST client for something much more specialized and narrow purpose than HTML. The main point of REST is that your client and server should both understand the media type, and then be developed independently to have all the semantics of that media type.

HTML is not a special media type in this sense. It just happens that it's an extremely broad format, broad enough to encompass almost the entirety of the web. But not all REST APIs need to be this broad: you can create specialized REST APIs for specialized media types.

In principle, the definition of a true REST API would be: can you create a a fully conforming client for the REST API by just reading and implementing the definition of the media type + using the HTTP verbs? If yes, then the API is truly REST like. If you need any other out-of-band information, then it's not. Note that knowing URLs is already out of band information.

[brabel]

Completely agree... it's just that it's very rare to see truly hypermedia-driven APIs out there, other than the Web itself.

I've seen only one, and that's one I helped develop.

[tuukkah]

> It displays the hypermedia the way it is given without knowing the semantics at all - that's what makes it de-coupled from the server. It only knows the semantics of the hypermedia, in this case HTML.

I don't think this is true in the general case. Yes, you can make a hypermedia browser/"viewer" that doesn't understand any semantics apart from links and depends on HTML+CSS for presentation. But you can also make a hypermedia browser that knows the semantics such as microformats or RDFA.

JSON-LD is in a practical sweet spot because it has links and also structured data. Obviously, you don't view JSON-LD with a web browser directly but with a browser that has another presentation layer in place of / in addition to HTML+CSS. The downside is you have to agree on and implement a presentation layer, the upside is it can be much simpler than a web browser plus you get machine-readable data with semantics.

[runeks]

> Have you looked into JSON-ld? Sure it is an extension of json but it has a formal specification which solves all the problems you have with your json examples, specifically the out-of-band issue you have with your json and how to link to other things.

Which problems does it solve, exactly?

When I read the JSON-ld examples I see fields containing @-prefixed links to other JSON documents, but why not just include that JSON in the original document, instead of linking to it?

[chriswarbo]

> When I read the JSON-ld examples I see fields containing @-prefixed links to other JSON documents, but why not just include that JSON in the original document, instead of linking to it?

A few reasons:

- It avoids bloating the response, especially if the referenced data contains other references, and so on.

- It allows cycles, e.g. person A's "spouse" can reference person B, and person B's "spouse" can reference person A.

- We can reference things which we don't know, or haven't bothered to calculate, or aren't permitted to access, or which don't even exist yet. All we need is their URL.

- References aren't simply locations (URLs, which we can GET), they're also identifiers (URIs). URIs let us reference a particular thing, whereas an embedded value might be ambiguous. For example, the value `{"firstName": "Tom", "surname": "Cruise"}` might be talking about the famous actor, or some other person called Tom Cruise. In contrast, a reference like "https://dbpedia.org/page/Tom_Cruise" only refers to the actor.

- URIs are quick and easy to compare, whereas JSON values are computationally harder to compare (especially if we're inlining a whole bunch of related values), and ambiguous; e.g. in the Tom Cruise example above, is that JSON object the same (semantically) as one which also contains `"birthDate": "1962-07-03"`?

[berkes]

> why not just include that JSON in the original document, instead of linking to it?

For me, the reason I'm linking and not including is bandwidth (and load of (de-)serialization). The age-old "pointer vs value" optimization.

When you go overboard, the "state" part of the payload becomes a large part of whats being sent. I've worked with APIs where over 80% of the data was this "cruft" and only 20% was the actual data. It happens esp when you compose your API of many small objects - which in itself has tradeoffs but is often a good practice.