There Are Many Paths to API-First—Choose Your Own Adventure

Kin Lane

May 2, 2022

API-first is an important topic, but it’s also one that’s sometimes misunderstood and miscommunicated. This can produce anxiety, confusion, and even hostility as organizations discuss what qualifies as an API-first approach. As chief evangelist here at Postman, I recognize how important these discussions are. There’s a significant meaning and purpose wrapped up in the API-first concept. With the right approach, API-first will save your team pain and suffering, and save your organization time and money. This can ultimately spell the difference between remaining competitive or falling behind in today’s digital landscape.

APIs are powering our world

APIs are powering everything around us. They are behind our desktop, web, and mobile apps, and also connect everyday objects like signs, appliances, and cars to the internet. When we use these objects, we tend to focus on the interface that we use to control them. But just beneath the surface of the apps, APIs are doing the heavy lifting, enabling connectivity and performing other meaningful actions. API-first is simply about “seeing” the APIs as equally important–if not more–than the surface application. And recognizing the privacy, security, and reusability that result when APIs are prioritized.

API-first is about prioritization

You don’t get tap water without pipes, nor electricity without power lines. And you don’t get digital resources and capabilities in business situations without APIs. API-first is about acknowledging that you must prioritize APIs to achieve the connectivity, productivity, and quality you desire across your teams. Being able to govern your business operations requires observability and control over the state of your enterprise at any given moment. And with operations increasingly defined by APIs, API governance is how you get there.

Related: Enterprise best practices: successfully govern your API content and users

The beauty of API design-first

API design-first is a subset of an API-first strategy. It’s the North Star for many teams that embark on an API-first journey. API design-first is about designing APIs in a collaborative way before you write code or release anything into production. It’s about using the OpenAPI Specification to define and design the surface area of your API; generating a mock server for other stakeholders to practice with and understand the API; documenting the API; and gathering feedback from stakeholders on how to improve it. Then iterating upon the design until you have an API contract that meets the needs of consumers, as verified by tests during development. API design-first is about making sure APIs meet the needs of consumers. You are able to iterate rapidly and ultimately come out the other side with a human- and machine-readable contract that can be used to validate the API in production, ensuring that nothing has changed over time.

There is still a lot of confusion

In the world of APIs, there is confusion about what constitutes API-first. Many of us who see the potential of API-first, and specifically API design-first, can get a little nerdy about it while talking about it with other teams. We don’t always recognize some of the realities on the ground within the enterprise. Sometimes describing API design-first as our North Star can confuse the people we want to reach, making API-first transformation across the enterprise difficult. I’m looking to help alleviate this confusion with more precise storytelling, talks, and workshops. I believe we can widen the API-first approach to be more inclusive to all teams, reducing the friction we encounter as we work to win hearts and minds across enterprise organizations.

Different paths towards API-first

API design-first is the most logical and healthy approach to achieving API-first because it allows teams to move faster while ensuring producer and consumers stakeholders are on the same page. However, there are API-first approaches besides API design-first, including:

• Code-first: You prioritize coding the API before you code the applications that use it.
• Prototype-first: You develop, mock, and document your API using a collection before generating an OpenAPI definition. It is also common to use a proxy or Postman Interceptor to reverse engineer APIs, generating a collection, and then ultimately an OpenAPI from the collection
• Proxy-first: You run your existing API through a proxy or Postman Interceptor, and generate a collection based upon existing traffic
• There is also good old-fashioned handcrafting of a Postman Collection for an existing API and then generating an OpenAPI from that collection

To qualify as API-first, each of these approaches must produce an API contract that ensures everyone is on the same page, is validated as part of operations via tests, and automates the API lifecycle in a machine-readable way.

Find your favorite approach to achieving API-first benefits

In the end, I am not concerned with how you get to API-first. I’d be glad to see your teams equipped with design-first, code-first, prototype-first, proxy-first, or manual approaches to delivering, operating, and iterating upon APIs. You just need to make sure there ultimately is an API contract that can be used to power documentation, be validated using contract tests, and ensure the API is discoverable by producers and consumers.

The OpenAPI will provide you with a source of truth for the entire API lifecycle, enable collaboration, observability, and lay the foundation for governance. If you can meet the needs of your consumers, and continue delivering value within the web, mobile, and device applications, as well as system integration, nobody will care how you got there. Design-first is definitely the ideal way for teams to approach their API-first journey, but there should be less disagreement on the chosen path and more focus on the journey and transformation of our organizations.

Personally, my favorite approach is prototype-first. As much as I love editing an OpenAPI definition, I find creating a collection, mocking, documenting, and iterating upon a new API to be the fastest way to get to the real thing. I actually find myself operating the API in this fashion, adding data as examples, and building my applications and integrations on top of the mock server for weeks or even months.

Then, after I have stabilized my underlying data model and fleshed out how the API will be consumed, I generate an OpenAPI, produce contract tests, and then get to work developing an API.

I find this to be the best of both worlds, but this is me. I understand this approach won’t work for everyone, and I am not about to disparage different approaches. They just need to produce an API that makes consumers happy. Ultimately, we should spend less time criticizing folks who are code-first or telling the API design-first folks they are slowing things down, and find a way to embrace multiple approaches within our enterprise organizations.