I’ve always loved HTTP APIs. I remember reading about REST and hypermedia concepts for HTTP when I was at University, and I was blown away by the concepts.
In 2009 though, much to my disappoint, most HTTP APIs on the web had taken the HTTP transport layer and completely destroyed it for their use cases with no regards for HTTP Methods, hyper-linked resources, or use of the URI to address resources.
It was in 2011 when I first wrote PokeAPI - an open and free HTTP API offering a REST-like interface to the world of Pokemon.
Being about Pokemon gave it popularity that I did not expect, but the content of the API was secondary to the design of the API: I wanted to show the internet, in my young, just-out-of-university arrogance, that this is how HTTP APIs should be.
It’s worth understanding that back in 2011 the concept of Swagger (which later became OpenAPI) was brand new and the age of the SAAS product was dawning with the likes of companies like Twilio (where I later went to work) and Stripe leading the charge of new products that offered an API as it’s primary means of connectivity.
Developer Experience == User Value
Over the next 12 years I journeyed through various companies gathering experience writing all sorts of applications and products, and always, always, there was an HTTP API involved, and I made sure we built it right.
But over time my strong opinions became more pragmatic as I realised that what really mattered was how easy it was for the developer to understand, test, integrate, and ship an HTTP API into their product.
I realised that the value of software is how quickly and confidently it can deliver value to users, and this fed backwards into those things I just mentioned above for an API:
Does it have good documentation that I can read and understand?
Is there some sort of OpenAPI schema I can use to potentially generate a client for my programming language?
Is the API easy enough for me to understand and debug that I can just play with the HTTP Methods and URIs to get what I want?
How safe and secure is the API for authentication and authorization?
These are the things that really matter, not how RESTful an API is (though that in itself can be a good indicator of how much care has been given to the design).
So I’m reviewing HTTP APIs now
This brings us to now, and I have quite a good number of years of experience working with HTTP APIs, building them, integrating them, and helping open source projects offer good tools for them.
I want to give my clear opinion on what makes a good API, what makes a bad API, how API services can improve, and how the whole ecosystem of APIs can continue to evolve to focus on that Developer Experience.
Let me know if you have an HTTP API that you like or loathe, and want me to review.