What if we stopped trying to write specs for new general-purpose hypermedia formats and redirected our efforts in a different direction?
Let me back up a bit, so I can explain myself. I’m the person in a group of randomly selected programmers who talks about APIs. Therefore, when it comes time to start working on what the API is supposed to look like, it’s pretty common logic that the person who talks about APIs the most gets to design the API.
Thus, lately, I’ve been working on some API definitions. The catch? People actively don’t care about Hypermedia and the promises thereof. In fact, there are a bunch of people who would be perfectly happy if we implemented a segment of a really bad API for a competing project where the best thing that can be said is that it’s not SOAP or XML-RPC.
I was working on pagination. I’m an avid fan of not bikeshedding, so I just borrowed bits from someone else’s specification. I picked JSON API. Thus, my swagger specification gained a links tag for a few of the objects I was creating in Swagger. I wasn’t implementing JSON API properly, but at least pagination worked exactly the same.
Some time passed, the swagger spec was reviewed, and then I was asked about errors, which I hadn’t really thought of. But I remembered a conversation with Luke Stokes from FoxyCart about a year ago and he pointed out the vnd.error spec, so I used it.
Which then meant that my errors had a _links tag, but everything else just had a links tag. I sighed, decided that since I wasn’t actually implementing JSON:API, it wasn’t a huge problem, so I moved everything to _links and moved on, filed in the back of my brain, and then came back to it this weekend.
Excepting JSON-LD, with is a beautiful and unique semantic snowflake, here’s where the “links” are stored in the popular hypermedia API standards:
| Format | Path to the link relation |
|---|---|
| ATOM XML | atom.links |
| Collection+JSON | collection.links |
| HAL | _links |
| SIREN | links |
| HTML/XHTML | html.head.links |
| JSON:API | links |
| UBER | uber.links |
It turns out that most of the popular libraries for doing requests are extensible enough that I can write neat little plugins that wrap them. So, if there was a bit more standardization, I’d be able to write a really absurdly generic hypermedia-esque client.
“But wait”, you say, “All you need to do is set maybe one variable when you instantiate your paginated client… and really, you can probably make a general-purpose rule that will work most of the time!” True. Also, regardless of where the links section lives, I can still probably look at it myself with curl and figure things out myself, which is the really important part.
But, back to the subject of selling Hypermedia to the rest of the world. We’re on a utilitarian project for an audience that, frankly, isn’t going to be impressed by any sort of fancy Hypermedia API design.
Most of the current answers and writings that someone tried to write up to answer all of the bikeshedding about hypermedia are trying to be ‘all-bikeshed’ answers. Maybe what hypermedia needs is more ‘single-bikeshed’ answers where, even if we end up with a big-end-of-the-egg tribe and a small-end-of-the-egg tribe, at least we can agree on a few things in a few areas.
Maybe what hypermedia needs is more single-bikeshed answers and fewer all-bikeshed answers. Even if there were two answers (say, one that starts with _link and one that starts with link) instead of n answers, you’d at least be able to point to yourself as a big-end-of-the-egg tribe or little-end-of-the-egg tribe.