3 ms·

I’ve implemented hypermedia APIs before. It was a lot of work for exactly zero benefit because none of the client developers wanted what they were given in thos

I’ve implemented hypermedia APIs before. It was a lot of work for exactly zero benefit because none of the client developers wanted what they were given in those APIs, and we were forced to develop _additional_ APIs that gave the client developers something they felt comfortable working with.

recursivedoubts 5y ago
Were the hypermedia APIs returning HTML or some other real hypermedia? I assume not. Were they consumed by a hypermedia client? I assume not, since there is nothing to complain about except compliance with the hypermedia specification in question. Hypermedia APIs never made sense once we flipped to JSON apis, it was all cargo cult. I've written some essays on this: https://intercoolerjs.org/2016/01/18/rescuing-rest.html https://intercoolerjs.org/2016/01/18/rescuing-rest.html https://intercoolerjs.org/2016/05/08/hatoeas-is-for-humans.html https://intercoolerjs.org/2016/05/08/hatoeas-is-for-humans.h...
- halostatue 5y ago
  Your premise about “HTML or some other real hypermedia” is bunkum. There is nothing about REST or HATEOAS that depends on HTML at all. The whole _point_ of REST was to build on the semantics of HTTP without regard for the transport protocol or encoding format (and HTML, XML, and JSON are all encoding formats). What makes a RESTful API a HATEOAS API is that it provides you actionable hypermedia definitions. There is fundamentally no difference between: <link rel="self" href="https://my.server.example/api/customer/id/1"> and { "link": { "self": "https://my.server.example/api/customer/id/1" } } When you include child responses, you include reachable endpoints for them, too. { "link": { /* top-level item refs */ }, "posts": { "link": { /* post collection level refs */ }, "items": [ { "link": { /* post level refs */ }, /* the rest of the object */ }, /* more objects */ ] } } And yes, in fact, that is _exactly_ what the API that I developed did—so every application client that worked against the API was required to work based on that (and it made making Postman collections really interesting, because you could not just “guess” at the URL required, you had to look it up through the chain). It worked. While it felt nicer from a “purity” standpoint, it made the server slower, less agile to client requirements. We eventually abandoned it as a mistake in the next generation platform that we built. There are a lot of good things about REST, and I like the idea of having discoverable APIs as expected in HATEOAS. But the number of people who _get_ it on the client development side is vanishingly small, and there’s always unfortunate drift where you get people templating API URLs even though they are given the exact API URL required to perform an operation. These days, I’d much rather write up a good GraphQL API with Absinthe and just get the job done rather.
  - recursivedoubts 5y ago
    No, it isn't, and the fact that you found it to be useless in a JSON API is evidence for my claim. The problem here isn't the API you designed per se: sure you can encode a hypermedia on top of anything, even JSON. The problem is the clients aren't hypermedia clients and don't want to interact with the API in that manner. They aren't using hypermedia as the application of engine state, they aren't taking advantage of the uniform interface and all the rest of it. If you read "HATOEAS is for Humans" I try to explain why that is. All the problems you are pointing out are due to the fact that your hypermedia-on-top-of-JSON API is being consumed by non-hypermedia clients who, at the end of the day, just want a powerful RPC/Query mechanism. Which is fine, I'm glad you came to your senses and gave that to them. But, to return to the original point, if you are just trying to get forms into databases, hypermedia is much simpler.
    - halostatue 5y ago
      I read your articles. I disagree with your foundational premise. HTML is a presentation / structure mechanism. HATEOAS isn’t _only_ for humans, but HTML is. The APIs that I built _were_ hypermedia. The only way to properly use them was to follow the links in the data. The problem wasn’t the APIs or even the software clients. It was the developers who didn’t see the point of it and ended up developing versions that broke the pattern. If all you have to worry about is a web browser, then you can start from your foundational premise. Most of us have to deal with all sorts of clients.
      - recursivedoubts 5y ago
        > It was the developers who didn’t see the point of it and ended up developing versions that broke the pattern. lol, cool man, take a week or two to think about that and then maybe reread my article :beers:

recursivedoubts 5y ago

Were the hypermedia APIs returning HTML or some other real hypermedia? I assume not. Were they consumed by a hypermedia client? I assume not, since there is nothing to complain about except compliance with the hypermedia specification in question. Hypermedia APIs never made sense once we flipped to JSON apis, it was all cargo cult. I've written some essays on this: https://intercoolerjs.org/2016/01/18/rescuing-rest.html https://intercoolerjs.org/2016/01/18/rescuing-rest.html https://intercoolerjs.org/2016/05/08/hatoeas-is-for-humans.html https://intercoolerjs.org/2016/05/08/hatoeas-is-for-humans.h...

halostatue 5y ago
Your premise about “HTML or some other real hypermedia” is bunkum. There is nothing about REST or HATEOAS that depends on HTML at all. The whole _point_ of REST was to build on the semantics of HTTP without regard for the transport protocol or encoding format (and HTML, XML, and JSON are all encoding formats). What makes a RESTful API a HATEOAS API is that it provides you actionable hypermedia definitions. There is fundamentally no difference between: <link rel="self" href="https://my.server.example/api/customer/id/1"> and { "link": { "self": "https://my.server.example/api/customer/id/1" } } When you include child responses, you include reachable endpoints for them, too. { "link": { /* top-level item refs */ }, "posts": { "link": { /* post collection level refs */ }, "items": [ { "link": { /* post level refs */ }, /* the rest of the object */ }, /* more objects */ ] } } And yes, in fact, that is _exactly_ what the API that I developed did—so every application client that worked against the API was required to work based on that (and it made making Postman collections really interesting, because you could not just “guess” at the URL required, you had to look it up through the chain). It worked. While it felt nicer from a “purity” standpoint, it made the server slower, less agile to client requirements. We eventually abandoned it as a mistake in the next generation platform that we built. There are a lot of good things about REST, and I like the idea of having discoverable APIs as expected in HATEOAS. But the number of people who _get_ it on the client development side is vanishingly small, and there’s always unfortunate drift where you get people templating API URLs even though they are given the exact API URL required to perform an operation. These days, I’d much rather write up a good GraphQL API with Absinthe and just get the job done rather.
- recursivedoubts 5y ago
  No, it isn't, and the fact that you found it to be useless in a JSON API is evidence for my claim. The problem here isn't the API you designed per se: sure you can encode a hypermedia on top of anything, even JSON. The problem is the clients aren't hypermedia clients and don't want to interact with the API in that manner. They aren't using hypermedia as the application of engine state, they aren't taking advantage of the uniform interface and all the rest of it. If you read "HATOEAS is for Humans" I try to explain why that is. All the problems you are pointing out are due to the fact that your hypermedia-on-top-of-JSON API is being consumed by non-hypermedia clients who, at the end of the day, just want a powerful RPC/Query mechanism. Which is fine, I'm glad you came to your senses and gave that to them. But, to return to the original point, if you are just trying to get forms into databases, hypermedia is much simpler.
  - halostatue 5y ago
    I read your articles. I disagree with your foundational premise. HTML is a presentation / structure mechanism. HATEOAS isn’t _only_ for humans, but HTML is. The APIs that I built _were_ hypermedia. The only way to properly use them was to follow the links in the data. The problem wasn’t the APIs or even the software clients. It was the developers who didn’t see the point of it and ended up developing versions that broke the pattern. If all you have to worry about is a web browser, then you can start from your foundational premise. Most of us have to deal with all sorts of clients.
    - recursivedoubts 5y ago
      > It was the developers who didn’t see the point of it and ended up developing versions that broke the pattern. lol, cool man, take a week or two to think about that and then maybe reread my article :beers: