Why do developers care about API-first?

Joyce

April 18, 2023

There’s a lot of talk lately about API-first as an approach to design and development. While there are many paths to API-first, usually the people driving this initiative within their organizations have job titles like API architect, API designer, and API platform leader. It makes sense because they are most invested in the efficiency, interoperability, and quality of the organization’s APIs.

And so these advocates establish API guidelines and standards to share with the rest of the team. For developers, API-first design might seem like a noble goal, but frequently the intent and urgency to implement the approach wanes. Consequently, developers may find it tough to adhere to these policies.

Managers care about API governance. Why should everyone else care?

Let’s inspect the organizational factors driving these behaviors, and learn how teams have successfully addressed this dynamic.

Reasons developers like API-first

Intellectually, developers know that API-first enhances their productivity, increases the quality of their code, and improves the overall user experience they are building. But when you dig into why developers actually like API-first, these are some of the reasons:

• Building things people want: early socialization with stakeholders through a contract or mock gives them confidence in what they build, without scrapping and rebuilding later in the development process
• Taking less time: once the initial design is agreed upon, the API contract can then be used to auto-generate code, documentation, contract tests, and mock servers

Building awareness about the outcomes an API-first approach enables is the first step in the API-first journey. We see several teams backing into API-first in practice solely because developers want to auto-generate code, docs, tests, and mocks.

Reasons developers don’t like API-first

When you look at teams tasked with using tools like OpenAPI to design their APIs, doubts often stem from the following reasons:

• Takes more time: there is up-front work involved in the design process and to gain alignment between stakeholders on the API contract
• Cognitive load: planning for user scenarios from scratch can be overwhelming if your team doesn’t have existing definitions and guidelines to leverage
• Good enough: the current process is working good enough, and although there is a better way to do things, it’s not a priority at this time to change it

In the next section, let’s see how teams have addressed these doubts to gain buy-in among their developers.

Ways to drive adoption of API-first in your organization

It’s natural for developers to be reluctant to adopt a new process. Your team might still have unclear goals and be learning new tools. But it’s essential that the end goal and means to get there are supported by both leadership and practitioners in order to fully reap the benefits of API-first.

Depending on the stage of your API journey, there are different ways to increase adoption of an API-first design and development process.

• Build awareness of the outcomes an API-first approach enables
• Establish a governance body or person to create best practices and processes, and offer support for developers
• Provide best practices and guidelines to simplify decision-making
• Create an internal catalog of definitions to reference
• Offer reusable components for faster development and consistent design
• Automate feedback loops like API linting and other policy-as-code
• Measure progress via API metrics like development time, bugs, usage, and adoption
• Align incentives with key objectives to drive the desired behavior

It’s a journey

API-first design takes more time up front to plan and gain alignment among stakeholders. But once the design is agreed upon, it can save time auto-generating deliverables throughout the rest of the API lifecycle. Time is also saved in subsequent development cycles since rework is minimized.

Similarly, at the very beginning of an API-first journey, it takes time and resources to develop guidelines and reusable components to share with the rest of the organization. But once the process is sorted, teams see increases in developer productivity, quality of code, and user experience, which consequently results in overall developer happiness.

Be flexible. API-first is not a one-size fits all approach. Learn more about API governance and how to enable organizational changes.

• “How to enhance your API design process” blog post
• “3 tips to get people comfortable with API governance” blog post
• Develop the Right API Governance Model for Your Organization whitepaper

Technical review by Kevin Swiber.