Building software is pretty easy, when it comes down to it. Generative AI tools like Chat-GPT that can spit out web applications with only general instructions are proof of this. The problematic part of this is that you don't just need software, you need to tailor it to your specific usecase. Put as a metaphor — it would be easy to write a wedding speech for some imagined couple. For specific people that you know? That's much harder and requires context.
What's that got to do with API design? Well, you need to know the people you're building your API for. That's actually a really big ask. The Correct™ solution is to prompt your target audience for information through questionnaires, feedback forms and other requirement gathering methods. This is called data driven design, and suffice it to say it's important for large companies and yields results. I'm not going to talk much about it, however.
Odds are you don't have the time or money to pursue this method of nailing down requirements, and perhaps more importantly, these types of high level actions are outside your responsibility. Engineers are gonna engineer, so we'll focus on that and assume we have a kinda good idea of our end-users needs.
Regardless, our much talked about context doesn't just come from understanding our users. It also comes from our understanding of the solution space, ie. how are current APIs built? This sort of makes sense. If we had perfect knowledge of the existing API solutions out there, we'd probably have a pretty good idea of what our solution could look like. Perfect knowledge of all existing APIs is again, a big ask. Plus, many APIs out there aren't using modern processes, are implemented imperfectly, etc.
One approach we might propose is to look at the general case of the modern API solution. If we examined 1,000 popular APIs and extracted out their common features, we'd probably have a pretty good candidate API solution. There's one issue with this approach, however. The popular APIs of today were designed years ago, by developers with different skillsets to today, with an internet that was different to today. They are essentially the products of APIs designed years ago that have evolved over the years to their current stage. Useful to look at? Absolutely — but ideally, we want to design our APIs by today's standards, not modified APIs based on standards from years ago.
The best solution would be to go forward in time a few years, examine the popular APIs of the time, see how they evolved and then copy them. The next best solution is to understand why the APIs of today had to evolve. To do that, we need explore the history of API design and development from as far back as we can and then from there, build up our idea of what a modern API should look like. That's what this blog series explores!
This is an ongoing series of blogposts about API Design. Stay tuned for more posts!