Getting to the Bottom of What It Means to Be API-First

In the API community, there is an ongoing discussion between design-first and code-first approaches. Many advocate for the tenets of API-first development and even implement a specification-driven approach to API design. In contrast, others note that API design often looks quite different throughout the software engineering world. “Is design-first API development real? Or are we just dreaming?” asks API evangelist Kin Lane.

Postman’s 2024 State of the API Report found that API-first development is rising. However, findings also indicate that gaps remain in how it’s executed. I recently met with Noah Schwartz, Head of Postman API Network, to discuss the latest trends in the API industry and what the future may hold for API-first development. Not surprisingly, he’s a proponent of the API-first approach. “When you’re API-first, problems like sprawl and drift can go away,” he says.

A design-first approach to API development can solve numerous challenges, including UX/UI issues, breaking changes, poor developer experiences, and others. Below, we’ll review some of Postman’s findings and try to unpack what it truly means to be API-first and where the industry appears to be headed. Hint: the future is not too different from the ubiquity of version control systems.

The Disconnect Around API-First in Practice

One seeming mismatch in this year’s Postman State of the API Report is the pervasiveness of API-first versus how developers are coming to learn about APIs. “74% of respondents are API first in 2024, up from 66% in 2023,” found the study, which surveyed over 5,600 developers and API professionals this year. API-first development is becoming popular as it reaps faster production times and better failure recovery.

While 58% of developers use internal documentation to learn about APIs, a significant portion of folks (44%) say they dig through source code to understand them. Many also depend on chat or email to learn about APIs. This is odd. If organizations were truly API-first, you’d hope they’d have the specifications to describe their APIs, easy-to-understand reference documentation, and developer portals that make this information discoverable and searchable.

To Schwartz, these separate findings suggest that although API-first is appealing, it has holes in practice. “This is pretty normal with tech adoption cycles in tech,” he says. “People say they believe in a thing and preach it but are not doing it fully in practice yet.” Perhaps many people believe in the API-first approach, but the rest of their company or tooling hasn’t fully caught up.

Double Clicking on What API-First Means

With API-first, you don’t work backward. Schwartz defines API-first as designing the API and cataloging it all in one place and following a source of truth, similar to version control. Following a source of truth, which typically means working from an API specification, can help avoid discrepancies in collaboration where different team members get lost working with varied information. He adds that this can be helped by documenting API calls and authorization details into a single integrated tool.

Developing APIs as an afterthought, on the other hand, can cause UX issues, API drift, and breaking changes. Instead, Schwartz stresses clarifying the API’s job and purpose up front and determining how it will interact with the UI before coding begins. Having conversations around data orchestration upfront can optimize UX, he says, helping to avoid returning data you don’t need, which could slow down performance or create unnecessary bloat.

Interestingly, the state of API-first adoption could be compared to the era before version control was standard practice. Nowadays, it’s unimaginable for a colleague to leave code on their local machine and not check in code into version control, says Schwartz. Similarly, he sees design-first API development becoming the inevitable norm. “The adoption cycle is lagging behind the preach cycle. It speaks to an opportunity to be API-first.”

Getting Everyone on the API-First Bandwagon

A recent report from APIContext found that 75% of APIs have non-conformant endpoints, suggesting that many APIs drift away from their “source of truth” in production. So, how can we encourage others to see the benefits of APIs and get more on the design-first bandwagon?

To Schwartz, API-first is all about collaboration. APIs are inherently a two-sided product, and collaborating early on brings benefits to stakeholders later on in the process. API-first helps the producer compose APIs to build across applications, and a platform-agnostic design is imperative to support this.

An API-first process can also aid versioning and deprecation strategies since integrations are more in sync. Yet, Schwartz admits that certain companies handle change management better than others. “At AWS, when we made a breaking change, which was rare, it wouldn’t happen until we talked to every customer. If we couldn’t reach everybody, we didn’t deprecate it.” He recalls that one API on an embedded system was eventually maintained for a single customer! Of course, modern SLAs might not allow this, but the story demonstrates a strong commitment to treating APIs as contracts and respecting the developer experience.

On that note, APIs must be easy to use, necessitating a greater focus on an API-first approach. “The responsibility around delivering an API has changed over time,” says Schwartz. “Good developer experience is table stakes now.” Having an easy time to first call and overall onboarding process will make or break an API product. Whether we’re discussing public or internal APIs, the expectation is usability and customer-friendliness on par with Stripe.

Future Outlooks for API-First: A Story for Every Industry

“All software will be an API,” says Schwartz. “As the product becomes the API, you’ll see more of a need for folks adopting it.” Getting today’s API-first advocates to fully transition into API-first practitioners will happen eventually. However, it may take a series of negative events — like breaking changes, outages, poor discovery, or even vulnerabilities — before the industry is fully motivated to make that shift.

“Drift is a byproduct of not being API-first,” Schwartz explains. In infrastructure-as-code tools like Ansible, for instance, drift detection features help ensure systems stay synchronized, minimizing unexpected changes. Similarly, investing in the right tools for API management can bring inspection and discovery capabilities, which help prevent API drift by keeping development aligned with evolving requirements.

Stronger API governance could also drive this shift. Although some think governance is a dirty word, executives are turning to governance to reign in API sprawl. Governance can also bring positive ripple effects, like ensuring healthcare systems comply with the FHIR healthcare API standard to properly transfer patient data. “Governance might sound off-putting, but its intentions are good. As long as it’s ultimately serving the customer, it’s a positive force,” Schwartz says.

Consider even legacy organizations like the USPS, founded in the 1700s, which now relies on hundreds of APIs at nearly every point of the logistics process. Massive API adoption is also happening across sectors like gaming, banking, and beyond. “In reality,” Schwartz adds, “there’s an API story in every industry.”