3 ms·

I don't understand why HATEOAS is incompatible with JSON. There's not a link/form standard like HTML, but there are still the standard HTTP verbs, and if you i

I don't understand why HATEOAS is incompatible with JSON. There's not a link/form standard like HTML, but there are still the standard HTTP verbs, and if you include a URL for each resource does that not meet the requirement? Stepping back a bit, I feel like people put Fielding's dissertation on a pedestal like it's some sort of perfect theoretical foundation that must be adopted in its entirety or not at all, but I see it more as simply exploring the idea of how to leverage HTTP instead of treating it as a dumb transport with no purpose but to add a layer of indirection like SOAP did. It was definitely a prescient thesis, but it also wasn't yet battle-tested in practice. I think HATEOAS didn't make the cut as a universally adopted practice because it doesn't provide all that much benefit. Sure it's nice in theory to be able to navigate around an API without any external queues, but even if you have in-built hypermedia standards like HTML forms, the purpose of an API is to perform some function, therefore you will always need some external semantic description of what you are doing. Contrast this with something like SQL where there is a mathematical foundation for manipulating rows and columns that is completely independent of any semantic weight the data may carry. I am definitely keeping an open mind that I might be missing some key insight, but to me there's just not a huge untapped promise of REST, it's just that we learned what works and what doesn't, and frankly it's worlds better than the bad old days of SOAP/WSDL.

carsongross 11y ago
JSON certainly isn't incompatible with HATEOAS in theory, but we have enough observational evidence at this point to conclude that it will not be used in practice, on any meaningful scale. From the article: HATEOAS is a constraint of the REST application architecture that distinguishes it from most other network application architectures. The is the under-appreciated aspect of regular old HTML is that it satisfies this requirement, and that makes HTML-based applications fundamentally different than (nearly all) JSON-based applications.
- dasil003 11y ago
  I certainly don't under-appreciate HTML. I was there at the University of Minnesota when the WWW appeared in our Gopher and set the world on fire, and I've made a career out of it ever since. But the magic of HTML is in the browser where you click around. Having a standard for form equivalents and links in a JSON API doesn't pack the same punch because there is little purpose to have freeform consumption of an API the same way that we have freeform consumption of web pages by humans. In theory I understand that tools could be built around rigid adherence to RESTful principles, and that this could allow some sort of usage without out-of-band documentation, but REST principles per se are not a specification for something that you can build tooling against. For that purpose I feel efforts like JSON-API (http://jsonapi.org http://jsonapi.org) are doing an admirable job, and whether it is technically RESTful seems like a minor footnote compared to whether it's making good decisions that A) prevent bikeshedding and B) enable better tooling.
  - sampsonetics 11y ago
    > But the magic of HTML is in the browser where you click around. Having a standard for form equivalents and links in a JSON API doesn't pack the same punch because there is little purpose to have freeform consumption of an API the same way that we have freeform consumption of web pages by humans. I think that's the whole point of the original article: If we're creating an interface for human consumption (a UI), then REST is eminently relevant, and we shouldn't forget the power of HTML-over-HTTP as its most widely-supported realization. But if we're creating an interface for programmatic consumption (an API), then REST is more problematic and we shouldn't feel guilty for not achieving its ideals.
virmundi 11y ago
You just have to keep in mind the goal of REST: self navigation. Given a known document, it should be possible to automatically navigate the graph of related documents. REST, technically, is a poor choice for an API. REST assumes, at least in my opinion, a human driver on the consumption side. A rendered page is for a human. REST coalesces HTTP. HTTP came first. To get anything useful from an API requires as much context as deriving meaning from an HTML document. REST, by itself, does not try to give a semantic meaning to the data. An API does. So take the useful and leave the useless. If you want to extend JSON to link, fine. Just make sure you document your new type. If you want to use just the noun + verb paradigm, go ahead. Please be consistent. Please document your assumptions.
weddpros 11y ago
The article assumes having HATOAS is somehow more important than having an API. Maybe it's not. SQL and JSON APIs share the same vision (dis)regarding HATOAS. A foreign ID in SQL looks like a JSON field with an ID in it. HATEOAS links are more like storing SQL statements as a foreign key. So if you think SQL did it right, so did JSON without HATEOAS. If HATEOAS was such a nice feature, everybody would use it in JSON APIs. Its proponents always say the world would be better with it, but the world disagrees.
- icebraining 11y ago
  I'd say that HATEOAS links are like foreign key constraints. In a JSON document, you get an ID, but there's no semantic information about what it refers to, it's just a number. In SQL, on the other hand, the table has that metadata, and so it can tell you that the number refers to a specific record of table <X> - just like the link in HATEOAS encodes the specific document it's referring to.
  - weddpros 11y ago
    Some databases don't even support explicit foreign key constraints, and SQL doesn't make their declaration mandatory. And that metadata is not in the resultset, you get an id instead. So SQL dbs will happily let you join with the wrong table. Also foreign key constraints don't play well with sharded SQL dbs. For these reasons, I don't see SQL as a good parallel to HATEOAS. Maybe an ORM would be closer to what HATEOAS brings... It's all about impedance mismatch I think... but HATEOAS is no more a definite solution than ORMs.
paulddraper 11y ago
Fielding's work isn't specific to HTTP. It was just agreeable with it.

carsongross 11y ago

JSON certainly isn't incompatible with HATEOAS in theory, but we have enough observational evidence at this point to conclude that it will not be used in practice, on any meaningful scale. From the article: HATEOAS is a constraint of the REST application architecture that distinguishes it from most other network application architectures. The is the under-appreciated aspect of regular old HTML is that it satisfies this requirement, and that makes HTML-based applications fundamentally different than (nearly all) JSON-based applications.

dasil003 11y ago
I certainly don't under-appreciate HTML. I was there at the University of Minnesota when the WWW appeared in our Gopher and set the world on fire, and I've made a career out of it ever since. But the magic of HTML is in the browser where you click around. Having a standard for form equivalents and links in a JSON API doesn't pack the same punch because there is little purpose to have freeform consumption of an API the same way that we have freeform consumption of web pages by humans. In theory I understand that tools could be built around rigid adherence to RESTful principles, and that this could allow some sort of usage without out-of-band documentation, but REST principles per se are not a specification for something that you can build tooling against. For that purpose I feel efforts like JSON-API (http://jsonapi.org http://jsonapi.org) are doing an admirable job, and whether it is technically RESTful seems like a minor footnote compared to whether it's making good decisions that A) prevent bikeshedding and B) enable better tooling.
- sampsonetics 11y ago
  > But the magic of HTML is in the browser where you click around. Having a standard for form equivalents and links in a JSON API doesn't pack the same punch because there is little purpose to have freeform consumption of an API the same way that we have freeform consumption of web pages by humans. I think that's the whole point of the original article: If we're creating an interface for human consumption (a UI), then REST is eminently relevant, and we shouldn't forget the power of HTML-over-HTTP as its most widely-supported realization. But if we're creating an interface for programmatic consumption (an API), then REST is more problematic and we shouldn't feel guilty for not achieving its ideals.

virmundi 11y ago

You just have to keep in mind the goal of REST: self navigation. Given a known document, it should be possible to automatically navigate the graph of related documents. REST, technically, is a poor choice for an API. REST assumes, at least in my opinion, a human driver on the consumption side. A rendered page is for a human. REST coalesces HTTP. HTTP came first. To get anything useful from an API requires as much context as deriving meaning from an HTML document. REST, by itself, does not try to give a semantic meaning to the data. An API does. So take the useful and leave the useless. If you want to extend JSON to link, fine. Just make sure you document your new type. If you want to use just the noun + verb paradigm, go ahead. Please be consistent. Please document your assumptions.

weddpros 11y ago

The article assumes having HATOAS is somehow more important than having an API. Maybe it's not. SQL and JSON APIs share the same vision (dis)regarding HATOAS. A foreign ID in SQL looks like a JSON field with an ID in it. HATEOAS links are more like storing SQL statements as a foreign key. So if you think SQL did it right, so did JSON without HATEOAS. If HATEOAS was such a nice feature, everybody would use it in JSON APIs. Its proponents always say the world would be better with it, but the world disagrees.

icebraining 11y ago
I'd say that HATEOAS links are like foreign key constraints. In a JSON document, you get an ID, but there's no semantic information about what it refers to, it's just a number. In SQL, on the other hand, the table has that metadata, and so it can tell you that the number refers to a specific record of table <X> - just like the link in HATEOAS encodes the specific document it's referring to.
- weddpros 11y ago
  Some databases don't even support explicit foreign key constraints, and SQL doesn't make their declaration mandatory. And that metadata is not in the resultset, you get an id instead. So SQL dbs will happily let you join with the wrong table. Also foreign key constraints don't play well with sharded SQL dbs. For these reasons, I don't see SQL as a good parallel to HATEOAS. Maybe an ORM would be closer to what HATEOAS brings... It's all about impedance mismatch I think... but HATEOAS is no more a definite solution than ORMs.

paulddraper 11y ago

Fielding's work isn't specific to HTTP. It was just agreeable with it.