Hacker News new | ask | show | jobs
by bobfromhuddle 4095 days ago
So much fear and loathing in this thread, which puzzles me. Anyone who sets out to write a hypermedia API in JSON is going to end up with a structure not dissimilar to this one. If this fits your needs, then use it, by all means and let your clients use an off-the-shelf lib for using your service.

I'm not a fan of the spec, but overall it seems to strike a good balance between what is specified and what is left out. To compare this to SOAP is missing the point.

What killed SOAP was an insistence on treating HTTP as a dumb transport - thereby breaking the constraints of the interwebs, the inherent brittleness of RPC, and the lunacy of the WS-* stack.

None of that applies here, it's closer in spirit to AtomPub, which is still a pretty decent standard, but just happens to be in XML which everybody hates nowadays.

I think a lot of the commentators in this thread seriously believe that having a different data format and interaction style for every API on the internet is somehow "simpler" than adopting a loosely defined set of conventions and writing them down somewhere as a standard.
1 comments
spopejoy 4095 days ago
It seems to me this standard is only really useful for APIs to be consumed by a specific GUI or GUI framework, as opposed to "data-centered" APIs that exist to provide access to a particular dataset for myriad purposes. Having a "links" section makes no sense in the latter case -- that's what docs/Swagger/RAML are for.

My stab at imposing some consistency on data APIs boils down to a header and a data section. The header's utility is in describing the data, most obvious utility comes from including a "count: 235" or paging data.

Less-obvious is having self-describing data, namely including the path and query parameters in the header, so you could ingest the data sans request and still know what it represents.

But it's a little bikesheddy, and that might be that data-only APIs are so freaking simple that no standard is really necessary. If so, I must question writing a standard around how we happen to build GUIs today as it seems doomed to SOAPy failure. But hey I'm not "full-stack" ...

link