3 ms·

A JSON data API and an HTML (view) API are two different animals and should use different end points. REST/HATEOAS doesn't describe accurately or work well wit

A JSON data API and an HTML (view) API are two different animals and should use different end points. REST/HATEOAS doesn't describe accurately or work well with JSON because it is not a hypertext. This is why newer JSON APIs are moving away from REST and towards things like GraphQL. REST/HATEOAS works great with HTML though, because HTML is a hypertext. You don't even have to think about it very hard, it just works. Read the above blog post, I explain this. People get hung up thinking I'm advocating adopting HTML for their public data API. I'm not. I'm advocating building your own web application in a restful manner against a separate set of HTTP end points and letting your data API satisfy the needs of your integration partners.

shortstuffsushi 10y ago
Perhaps I'm missing the difference between your examples in HTML vs XML. Ultimately it's just another view of the same data, which could be driven all via the same request with a different Accept header. JSON, XML, and HTML would all provide identical data and the other requisite links, etc, HTML is just inherently human readable (ish, assuming browser rendering). I've had a couple of interesting projects developed much in that manner, where a single API served both a website (browser default Accept is HTML) and mobile requested with JSON Accept. A simple middleware layer that varies the response (which is just some plain old xxx object) and returns the preferred media. I'm not sure that I agree that with your analysis of JSON. Semantically you're correct about it not being hypertext, but I don't think that precludes it as an effective media for a REST/HATEOS application.
- carsongross 10y ago
  That's the default in rails (view API and data API are the same controllers/shape using accepts headers). It's a mistake for anything beyond a basic data model, and maybe even for that. Read the blog linked above and the other articles linked from it, I explain the HATEOAS problem in more detail. JSON APIs are moving away from REST and towards a more RPC-style model, e.g. GraphQL. The industry is finally getting sick of shoe-horning JSON into a conceptual model that makes no sense for it. Anyway, intercooler is a different, simpler way to build web apps. If you are willing to split your data API out from your web app API, you can save a lot of complexity in your stack. We built a reasonably modern web app with it with no front end engineers, just a couple of gronky full stack guys with some rails experience, and not much more code than a normal rails app would require. We built our data API using Grape, rather than rails. Turned out very clean, decoupling the two. Yes, I am aware that I am telling you almost exactly the opposite of what almost everyone else does and that I appear insane.

shortstuffsushi 10y ago

Perhaps I'm missing the difference between your examples in HTML vs XML. Ultimately it's just another view of the same data, which could be driven all via the same request with a different Accept header. JSON, XML, and HTML would all provide identical data and the other requisite links, etc, HTML is just inherently human readable (ish, assuming browser rendering). I've had a couple of interesting projects developed much in that manner, where a single API served both a website (browser default Accept is HTML) and mobile requested with JSON Accept. A simple middleware layer that varies the response (which is just some plain old xxx object) and returns the preferred media. I'm not sure that I agree that with your analysis of JSON. Semantically you're correct about it not being hypertext, but I don't think that precludes it as an effective media for a REST/HATEOS application.

carsongross 10y ago
That's the default in rails (view API and data API are the same controllers/shape using accepts headers). It's a mistake for anything beyond a basic data model, and maybe even for that. Read the blog linked above and the other articles linked from it, I explain the HATEOAS problem in more detail. JSON APIs are moving away from REST and towards a more RPC-style model, e.g. GraphQL. The industry is finally getting sick of shoe-horning JSON into a conceptual model that makes no sense for it. Anyway, intercooler is a different, simpler way to build web apps. If you are willing to split your data API out from your web app API, you can save a lot of complexity in your stack. We built a reasonably modern web app with it with no front end engineers, just a couple of gronky full stack guys with some rails experience, and not much more code than a normal rails app would require. We built our data API using Grape, rather than rails. Turned out very clean, decoupling the two. Yes, I am aware that I am telling you almost exactly the opposite of what almost everyone else does and that I appear insane.