Skip to main content

Go API-first and take your team with you

A guide to building teams that ship great APIs. This guide compiles our leanings from helping teams of all sizes start working API-first.

Subscribe to the monthly newsletter and never miss a post:

Why are APIs different?

APIs have become the most important dependency in our stack. They allow us to collaborate at scale, and build software that is greater than the sum of its parts. If you are on a team that produces an API, then you know that it comes with a lot of responsibility. Unlike code dependencies, when an API is changed, it affects all of its consumers immediately. This means your team has the power to break other team’s applications whenever you deploy changes (no pressure). That is what makes APIs so different than any other kinds of development.

Deploying an API is like launching a satellite. Once it is in orbit, you can not really change it. If you are clever, you’ve added the ability to make orbital adjustments and small software upgrades (an evolvable API-design). But if you want to make fundamental changes, you have to launch another satellite and de-orbit the first.

The constraints of API development are why many teams try to work API-first. They want to build the right API, the first-time (before it gets to orbit). They want everyone on the team to be thoughtful about introducing new capabilities and changing the API. Most importantly, they want to keep their promises to consumers.

Designing APIs and Reviewing Changes

API Review

Review workflows

  • Design-first: Design, review, implement, ship [coming soon]
  • Code-first: Code, review, ship [coming soon]


Adopting OpenAPI

Once your API is written down, your team can talk about it. Imagine if code review tools only showed the commit messages, not the code? That would not bring out your team's best work. Once you have an API written down, you can talk about the use cases, what issues consumers may have, and have a much better shot at shipping the right API, the first time.

  • Documenting an existing API with OpenAPI (aka playing catch-up) [coming soon]
  • Versioning OpenAPI and versioning your API. Understanding the differences. [coming soon]
  • Helping developers write OpenAPI [coming soon]

Setting API Standards

  • Why API Standards are useful, and when they are not [coming soon]
  • How to choose an API versioning strategy [coming soon]
  • How to decide which standards end up in your API style guide [coming soon]
  • Evolving your API standards without getting in the way [coming soon]
  • Picking the right tools [coming soon]

Testing APIs (aka Keeping promises)

  • Making sure your API is behaving as designed [coming soon]
  • The various definitions of "working" APIs [coming soon]

Having impact without getting in the way

  • Stages of API-first-maturity [coming soon]
  • Getting developers to care about APIs [coming soon]
  • Making the "right way" easier than the wrong way [coming soon]
  • Don't get in the way [coming soon]