API-First Development: Architecting Applications with Intention

Move fast! Break things! As developers on an agile team, we repeat these words constantly, always at least right up until the moment when something actually breaks. Then it turns out, despite all our oft-touted slogans, what everyone really meant was: move fast without breaking things. Duh, why didn’t we think of that sooner?

I want to talk about API-first development because I believe an API-first approach will lead to a faster and more scalable approach to developing software applications without breaking as many things along the way.

What Does ‘API-First Development’ Mean?

API-first development prioritizes the design and development of the API as the foundation for your entire architecture. This means taking extra care to treat your API as a product in its own right, even if it’s only going to be consumed internally by your own developers. This might require a bit more planning and collaboration between stakeholders, but there are a lot of good reasons to invest a little bit of extra time upfront.

Why API-First Development?

More traditionally, tech companies often started with a particular user experience in mind when setting out to develop a product. The API was then developed in a more or less reactive way to transfer all the necessary data required to power that experience. While this approach gets you out the door fast, it isn’t very long before you probably need to go back inside and rethink things. Without an API-first approach, you feel like you’re moving really fast, but it’s possible that you’re just running from the front door to your driveway and back again without even starting the car.

API-first development flips this paradigm by treating the API as the foundation for the entire software system. Let’s face it, you are probably going to want to power more than one developer, maybe even several different teams, all possibly even working on multiple applications, and maybe there will even be an unknown number of third-party developers. Under these fast-paced and highly distributed conditions, your API cannot be an afterthought.

As a software system matures, its real value emerges from its integration into a more complex whole. Features and products are like big delicious juicy fruit hanging off a branch. Your API is the entire freakin’ tree!

How Do I Get Started?

So you’re feeling ready to dive into API-first development? Spectacular! Trust me, the little bit of extra work upfront will pay off big time down the road, and you’ll start seeing the impact almost immediately.

The first step is to design and document your API. Don’t worry, this isn’t as complicated as it might sound. Just create an API spec file. This file will serve as both blueprint and documentation for your API. There are several varieties in common use today (OpenAPI, Swagger, RAML and API Blueprint, for example). We don’t need to stress out about which one to choose right now. The important thing is that all of these specifications provide standardized and machine-readable representations of your API. This standardization pays dividends later by helping you collaborate better, work more efficiently, beef up security and seamlessly integrate with external systems.

Here’s the best part: Writing these specs is actually pretty easy. If you can handle writing the actual server code for your API, then you will pick up any of these specifications in no time at all. It’s a natural extension of what you’re already doing.

This may all seem a bit time-consuming at first, but trust me, that small investment up front will save you heaps of time down the road, especially once you start leveraging the power of code generators (Liblab for example). These tools can do all sorts of cool stuff like generating SDK and server code for your API. Imagine making a change in one place, and boom! It’s instantly updated across all your server code as well as the SDKs used by internal and third-party developers.

Wouldn’t that save you time? That’s the transformative power of API-first development.

Conclusion

An API-first approach might not be the perfect fit for every use case. If you’re working on a small app or a prototype with limited integration needs, going all out with extensive documentation and code generation might not be your cup of tea. Likewise, if you’re dealing with a legacy application with its own well-established API, convincing management to dedicate the time and resources to document that API thoroughly might not be feasible. In most other cases, however, adopting a more proactive API-first approach to development can unlock some serious benefits.

In today’s interconnected digital landscape, it’s high time that we start treating APIs as first-class citizens in our architectures. A top-notch API design sets the stage for innovation by enabling developers to leverage existing functionality in new and unexpected ways. On top of this, APIs fuel collaboration by boosting interoperability between systems. Given all these undeniable advantages, the only thing holding most developers back is a lack of knowledge. So buckle up then, and let’s write a spec!