conference logo

Playlist "BornHack 2023"

All API's suck, can we build one that sucks less?

Auke van Slooten

I've been building software that connects to remote API's for 20+ years, and it is still one of the most frustrating parts of my work. Even the best REST API's, with GraphQL and all, still require carefully crafted client code. Why isn't this solved already? Or if it is, why don't we use any of those solutions? Can we get out of the tar-pit?

One of the issues, I believe, is that REST is not well defined and not well fitted to the API space. JSON itself is too limited. The whole premise of REST is that the type of information defines the interactions you can have. JSON has just 5 types, and no links. So we've had to repurpose property names to stand in for types. That ends up creating all sorts of problems higher up in the stack. Linked Data and Solid (https://solidproject.org/) give a glimpse of a potential solution. Unfortunately Linked Data doesn't fit the mental model of most developers, and certainly doesn't fit the internal application data model of browser based javascript applications. Finally REST and Solid fundamentally muddy the waters by having URL's point to documents, which can have any data. So you can never tell up front which data to expect from a certain endpoint.

I will provide a few examples of well intentioned but unfortunate API's, from luminaries like Microsoft Azure, to less well-known, but more hilarious niche API's. Not to shame them, but to make it abundantly clear that creating a good REST API is almost impossible.

Then I'll present my own attempt at building an API that has meaningful data, Linked Data light, if you will, that is identical with your application data model, that is discoverable and predictable. Where you don't need to learn a new paradigm or new query language.

It's called SimplyStore, open source (MIT license) and can be found at https://github.com/SimplyEdit/SimplyStore/