API First: A Smarter Way to Build Software

API First has been growing in popularity over the years as a method of solving some common software development difficulties. If you want a deeper understanding of why anyone should care about API First and how to implement it, you’re in the right place.

What is API First?

API First is an approach to software development that puts priority on using APIs as the building blocks to deliver a product.

A more traditional “code first” approach might see you creating an application (front or backend) then building APIs to suit the code you’ve written. Using API first you would instead figure out what interfaces will be required before implementing any functionality.

But.. Why?

You probably wonder why it’s worth spending time to get your team into a position to use an API first methodology. After all, you can whip up a simple CRUD API no problem already, and who wants to spend time figuring out a new way of working?

For “My first todo app” a simple CRUD API might cut it, but increasingly we have more complex projects to implement. We often need to consider support on multiple platforms and products. Taking an API first approach encourages us to break down interfaces into building blocks, which increases re-usability of our code.

When it becomes time to start writing code we realise the next benefit, being able to work in parallel. Since we have an API design before implementation developers can work in parallel. That can be frontend & backend engineers, or developers in different teams. Everyone can work with mocks then when development is complete everything is ready to integrate seamlessly.

After that first project is complete, the next common hurdles are figuring out how to on board a new developer and implement the second project. If we have a clear API strategy, service discovery and composable interfaces this will be a much easier process.

These are the direct result of using API first, of course in actual terms this all results in faster development time, a better developer experience and reduced costs.

Great.. How?

Since API First is a methodology there is no prescription of “take these steps and use these tools” that magically make you an API First company in a day. You need to consider the steps and benefits you want to reap, and see which tools suit you. That said, we can talk about what needs to be considered to make sure you’re on the right track.

The key principle of API first is that API’s are treated as first class citizens, as products not an afterthought. A good exercise to kick off would be to imagine your favourite XaaS company. What did you look for when choosing to use their API’s? The features probably include a trusted API lifecycle, clear documentation, easy observability, and strong security.

API Lifecycles & Strategy

To ensure adoption of API’s they should be intuitive and trustable, the best way to ensure they are is to have a clear API lifecycle and strategy. If API’s have side effects or it’s unclear how they should be used, they probably won’t be. If you wake up one day and the API you depend on has been fundamentally changed without notice or versioning, you probably won’t use that API provider again. Having a well-defined lifecycle and strategy avoids these issues completely and builds trust and adoption in your APIs.

API Discovery & Documentation

Since the goal of API first is to compose applications from reusable API’s it’s essential that developers can explore services, understand how they work & should be used. If a team doesn’t know a service exists, it won’t be used; if the intention of the service is unclear, it will be misused.

Observability & Governance

If you can’t tell, or worse control, what’s going on behind the scenes of an API would you feel comfortable using it? If an API consumer is receiving errors there needs to be clear visibility of the issue, and a course of action to resolve it.

A part of your API strategy should also explain how security fits into your services. Consider the use cases where a consumer will need to restrict access to features and make sure it’s fit for purpose.

What tools can help me?

We previously said there was no prescription for what tools to use, and that is absolutely still true. But I’ll leave you with a few to get you started on your journey to becoming an API First company.

Azure API Management

This is Microsofts API Management platform. Out of the box it does a lot of heavy lifting for API First. It’s split into 3 parts:
• Developer portal
• API Settings
• API Gateway

The developer portal provides a centralised location for API discovery and documentation. It also supports purchases of API subscriptions, management of API keys, viewing analytics of API usage and testing of endpoints. It can be custom branded, and hosted or self-hosted.

The API Gateway plane is a functional layer which is exactly what it sounds like, an API gateway. It acts as a façade for internal and external API’s, comes with some logging and analytics, verifies API keys, caching, rate limits, and versioning. It’s main purpose is to make both consuming and providing API’s easier.

API Settings generally is used to control the other portals, by controlling access to API’s and adding API’s to API Management. As with the other layers, it also shows you analytics as the API provider.

For helping run and support API’s or manage API subscriptions, API Management is an excellent choice that does a lot with very little configuration or maintenance effort required.

Backstage

Backstage is Spotify’s open source developer platform. This is really a blank canvas for whatever you want a developer platform to be, it has a rich plugin library and good documentation on how to make your own plugins. Plugins cover everything you can think of. Some examples:
• Authenticating users using Github organisations
• Collecting analytics from AWS/GCP/Azure/DataDog/etc.
• Sharing company wide announcements
• Running CI/CD pipelines
• Viewing vulnerability scan results from Snyk/SonarQube
• Tech radar for tool adoption guidance and tracking
• There’s even a plugin that shows XQCD comics

Out of the box you get an API catalogue that helps track dependencies and ownership of services, and the ability to setup templates that ensure your team can kick off new projects in the right way.

Documentation and API specs live in your service repo and are automatically pulled into Backstage once they are added the first time. Allowing developers to maintain docs as part of regular code changes rather than a separate task that is easily forgotten about is a great benefit.

Backstage is a fair amount of effort to adopt and maintain, although there are cloud hosted versions which reduce this complexity. It really needs a spike and investigation to see if it’s what you need, but it is a powerful tool if everyone engages with it but smaller teams might not get enough benefit to outweigh the cost of using it.

SwaggerHub

Swaggerhub is a collaboration platform for designing, building and documenting API’s in a centralised location. It supports OpenAPI and AsyncAPI specifications and generates UI documentation for your specs automatically.

The API editor is compliant with standards to give error feedback and auto complete, and ensures the team has consistent API design. It can generate a mock for your API without writing any code, and supports reusability across multiple API’s for the same domain.

Once you’ve written your API it becomes discoverable, can track changes, versioning and issues. It supports the team in working together and sticking to your API lifecycle and strategy.