What It Means to Go API-First

What It Means to Go API-First

Posted in

API-first is no passing fad. Undoubtedly, the API-first approach is on the rise, as more companies attempt to reap the reusability, self-service nature, and network effect of API-based software consumption models. But what exactly is API-first? And what does API-first development entail?

We can think of API-first from two perspectives: the technical side and the business side. On the technical side, API-first is a lot like how it sounds. Instead of going straight to the code or designing the application and user interfaces, you first establish the connective tissue between microservices. API-first development puts the creation of the API and its consumption model ahead of other focuses.

With an API foundation in place, you can more easily support multiple platforms, like web, iOS, Android, or IoT. You can also combine data from multiple underlying APIs to create various frontend user experiences. To enact API-first development, teams often utilize shared style guides, standard specifications, and relevant tooling to ensure consistency across an organization’s tech stack.

But API-first is not just popular for internal microservices. On the business side, API-first is becoming a common (and trendy) model to base an entire company around. For evidence, as of Q3, the API-First Index by GGV Capitol tracks over 60 API-first companies that have raised $50 million or more, amounting to $14B in total funding. This new class of API-as-a-Product companies, such as Stripe, Twilio, AssemblyAI, Shippo, and others, are inherently API-first and cater to developers as their number one consumer.

At our API-First LiveCast, we brought in two expert speakers to dive deeper into what it means to go API-first. Below, we’ll review the main takeaways from the event to see how to embrace an API-first mindset within your organization.

Our API-First LiveCast featured Joyce Lin, head of developer relations at Postman, and Charlie Davies, CEO of TravelTime. You can watch the recording here:

API-First In A Technical Sense

For the 2022 State of the API Report, Postman queried over 37000 developers and API professionals on their API habits and preferences. When asked to define ‘API-first,’ the top chosen response was: “Defining and designing APIs and schema before beginning development.” The report found this answer to be the most common choice among API-first leaders.

Joyce Lin, head of developer relations at Postman, is quick to highlight the schema aspect of the above definition. Not only is API-first contrary to code-first, but being API-first really means being schema-driven. Popular API specifications, such as OpenAPI v2, OpenAPI v3, JSON Schema, and GraphQL, can be used to implement this sort of schema-driven development path. “A schema acts like an API contract so you can experience the design benefits and have an agreement between producer and consumers,” said Lin.

API-First Continuum

Where are you on the API-first spectrum? According to Joyce Lin, schema-driven is a pre-requisite to API-first.

Lin acknowledges that there are many flavors of API-first in the market, ranging in maturity from API-last, to prototype-first, design-first, and schema-first. Schema-first design takes design-first one step further and is arguably the most mature evolution of API-first on the continuum. With this contract, consumers can trust it to build their integrations against, describes Lin. She describes that the end benefits of having a single source of truth are earlier feedback, reduced development costs, faster development time and growth, and more resilient APIs. “An API contract is one of the biggest hallmarks of API-first.”

API-First In A Business Context

So, now that we have a brief overview of what it means to develop in an API-first manner, what does constructing an API-first business look like? How can a platform succeed in doing so? Charlie Davies, CEO of TravelTime, shared his perspective on what it means to embrace an API-first mindset. To Davies, API-first has meant refining their marketing efforts, honing developer experience, and, perhaps most importantly — learning when to say “no.”

Keeping APIs niche means realizing they’re not an end-to-end solution. As Davies shared in a blog post on Nordic APIs, one of the biggest mistakes his team made was around positioning.

“We knew that TravelTime could help optimize where to place a new hospital, retail park, or office space. But when we positioned ourselves as a solution to these problems, our customers expected us to have an end-to-end location recommendation SaaS solution.”

Their initial positioning led TravelTime to launch custom environments, change API specifications on a per-client basis, and go backward and forward with its clients to meet their needs. While this custom work was integral to building up the company at an early stage, it was not scalable in the long run. “We realized very quickly that there were some decisions that we needed to make. We had this problem of scale,” said Davies. “We were selling the building, not the bricks.”

By transitioning their marketing materials to hype the “bricks,” TravelTime found they could reach more customers. Impressively, they experienced a 93% uplift when copy on the home page emphasized API-first. “We now know our limits — we’re API experts,” said Davies.

API-First Benefits and Caveats

Building APIs early on within the design phase can bring many benefits to a business. For example, encouraging common interfaces makes your services inherently more reusable. By focusing on the consumption model ahead of other factors, you can significantly improve developer experience, making your applications easier to discover and build upon.

There’s a reason why the Bezos mandate has reached such a mythic status. As it helped Amazon, putting APIs first can aid software development and benefit externalization efforts if a company decides to open up a microservice to select partners or the wider public. Emphasis on a design-first approach also improves consistency from the onset, as you’re providing more guardrails for developers. API-first provides more flexibility to add or remove features and fits into agile development principles.

Of course, no approach comes without its caveats. And embracing an API-first approach has a few challenges. For one, it does require a significant culture change, and you really need buy-in across an organization to make it worth your while. This might require some lead time to implement.

Secondly, this approach means investing more into your developer documentation, as “docs are the product,” said Davies. On that note, an API-first company shouldn’t dictate how the service should be used too much. The product must appeal to many potential use cases and be understandable by different types of users, whether they are developers, architects, CTOs, or product managers. It can thus be a constant balancing act to refine the developer documentation and support materials.

Also, as Lin covered, becoming API-first does require abstract thinking and architectural planning, which is a step away from the code. You must consider how other engineers might want to access your resources. This kind of thinking goes against code-first mentalities of just getting things done quickly. API-first might also be a significant change to the usual development workflow, and you could be dealing with legacy technology that wasn’t built in this style. This could result in having to reimplement much technology, as was the case for Etsy.

Final Thoughts: API-First = Happiness?

“Everyone’s journey to API-first is never smooth — it’s always a continuous and iterative process,” said Lin. And at the end of the day, people care more about the outcomes that API specifications enable, rather than the exact technical processes in place, notes Postman’s Chief Evangelist and Breaking Changes podcast host Kin Lane. Thus, while it’s helpful to clearly define what a “pure API-first approach” looks like and the benefits therein, it’s good to acknowledge the reality that API-first is a continuum, with organizations functioning at various places.

Can API-first bring true happiness? Well, 75% of developers at API-first companies report being happier. Sustaining high morale in software development teams is proven to positively influence productivity and reduce burnout and turnover. So, you could say that going API-first is a developer-first decision. So, consider API-first as a means to empower your engineers with the tools and experience they need to enact easier integrations and more agile application development.