What API-First Stands For?

What is API-First?

API-First also designates companies whose primary business runs on one or several APIs. One common example is Twilio, which uses APIs to drive its business, using pay-as-you-go pricing on SMS, MMS, WhatApps messages, etc. Companies like Twilio tend to experiment and adopt new ways to expose their APIs, with a focus on delivering value and quick API adoption.

Despite the term having two definitions, you can already see how one overlaps the other: whereas companies that adopt API-First strategies to design their APIs may not necessarily be API-First companies, API-First companies all adopt API-First design strategies.

And even if your business doesn’t rely on APIs as much as API-First companies, you can learn a thing or two from the design approach.

API-First and API Design-First

When dealing with API-First in terms of the design and development of APIs, let’s say that the word remains highly conceptual. According to the 2022 Postman State of the API Report, when developers were asked what the term means for them, two different definitions emerged, which came close to a technical dead heat. “Defining and designing APIs and schema before beginning development” comes first at 39%, but close behind, at 31%, was “Developing APIs before developing applications or integrations dependent on APIs”.

Tyk explains the difference between the two definitions as, first, API design before the system development lifecycle, and, second, as understanding APIs like blocks upon which other systems will be developed.

The different methods to get to API-first

Kin Lane identifies different ways to implement API design-first strategies inside an organization while emphasizing that the way you choose is not the most important factor, just as long as the result is a validated and well-thought product, which is user-friendly for partners and API consumers alike:

• Design-first is the preferred method. It implies using the same language, not only between teams but also using a specification that can be read by both humans and machines. This is why the OpenAPI specification is a good option: this is a standard, language-agnostic interface description whose API reference can be generated in seconds. This is the perfect way to define the scope of your API and iterate, which is the first step in establishing an API contract between different stakeholders. This API description will be used to create mock servers to test the API and start gathering feedback from stakeholders while working on API documentation. Though this approach will take longer, it enables you to make more complete, user-friendly APIs, which cover more use cases.
• Code-first is prioritizing coding the API before the application that will use it. This is considered the fastest way to produce APIs as it requires less maintenance since the APIs are generally more straightforward and focused on one use case. But this can limit the value delivered by the API. If your goal is to provide a high-value API responding to business opportunities, then this method will prove limited.
• Prototype-first is a third way whereby developers usually start developing, mocking and documenting the API before generating the OpenAPI definition file, using a collection like Postman.

Benefits and challenges of API-first

Regardless of the approach you choose to develop your API, adopting an API-first strategy inside an organization comes with its share of benefits and challenges.

Since the API becomes the centerpiece, those benefits include faster-produced APIs with greater deployment and fewer failures, which simultaneously enhance innovation and generate greater value from business partners.

Other benefits include greater flexibility — each API is a product in itself — thus reducing dependencies. The developer experience is also improved, as it is being treated as an important element: implementation is simplified and coherence across the API helps API consumers understand its structure. The use of OpenAPI specification also helps establish interoperability by setting standards between systems and organizations.

But implementing API-First strategies can also bring frustration and confusion among teams. It involves a clear definition of what’s a stake, the objectives, and the path to accomplishing those changes. It needs to involve all the teams and establish a common language to alleviate misunderstanding. You can make this easier by:

• Defining a clear API strategy — what changes do you want to implement and why? Establish a meaningful goal every team can relate to.
• Focusing on key objectives — now that your strategy is established, you need to choose key objectives that will speak to any teams while providing a framework to iterate.
• Establishing a method — we just saw a few ways to design and develop APIs. Which one is right for you? It depends on the goal you just defined, each will require workshops to establish a workflow and create bridges between teams. Don’t hesitate to adopt a goal-setting framework like OKRs and project management inspired by Agile methods.

The API-First Business Model

Back to the Postman Report in which a third definition for API-First was provided by 18% of respondents: “Defining business requirements before defining and designing APIs”. This is the other pendent of API-First, the business one. As we saw earlier, an API-First company is a company whose primary business is based on one on several APIs. In short, they give access to a wide array of features with just a handful of lines of code.

The API-First index from GGV tells us that the top API-First companies raised an estimated $14 billion, but what are their business model and specificities?

What is the business model of API-First companies?

According to Packy McCormick, there is a “sweet spot” for API-First companies on a segment of services that are both essential, but non-core for their customers. The business model of API-First companies can be defined as both focused and scalable:

• Focused, because those companies usually solve one specific issue — from payments with Stripe, to background checks with Checkr. API-Firsts have the competitive advantage of providing a first-class service because of this focus: their product will usually be far more complete and loaded with integrations.
• Scalable, from the start the APIs provided by API-First companies are made to serve thousands to millions of customers. The sheer volume of usage enables API-First to manage multiple complex processes in the background because their simplicity of integration and use makes them essential parts of third-party businesses.

The motto of API-First companies is to make simple something that used to be complex, by managing this complexity on their side and using APIs to access those services. Such services help companies create and add services in record time.

For example, you can create a service that relies on Google Maps API to manage geo-tracking and routes, Twilio to send service APIs, Stripe to manage payments, and you have a Uber-like app that can track drivers in real-time, call and send messages to customers and process their payments. And from your service, you can create your own API to distribute it to third parties.

Specificities of API-First Businesses

Beyond the business model, the API-First company possesses other specificities that make them different from other SaaS.

They tend to have two layers of users, product owners or managers that will discover the API and explore the possible value provided by it, and the engineers who will implement it. This implies two types of value propositions, one that emphasizes the service and the other the ease with which it is implemented.

Pricing is quite different from the average SaaS too. In our Report, we highlighted the fact that API-Firsts tend to use a pay-as-you-go pricing model. And even though some have kept the subscription-based model, all of them use units as the key billing metric, which are more or less API calls.

And, of course, the service provided is not to help users, but rather to get things done automatically. If the average SaaS is judged on the range of features it provides, the API-First company will be judged on its ability to completely take care of a specific domain.

Grace Isford summarized those specificities and emphasized the ones that make an API-First company successful. In addition to what we saw about the “sweet spot”, it includes:

• Making simple something complex, while providing a clear ROI in terms of time or money. She also points out that the end user isn’t aware of those companies.
• Timing and taking advantage of new usages, successful API-Firsts have seen their business explode at turning points — like the massification of the signup process and the need for SMS authentification in the case of Twilio.
• Community effect — such companies tend to be evangelists among the developer community as well as invest in user communities. Stripe’s API documentation became a reference everyone strives to reproduce and Twilio used to give a lot of free credits to test and use their services.

Examples of API-First Strategy Implementations

To illustrate the above, we’ll now review two examples of companies that use API-First strategies. The first is Etsy, which is not an API-First per se but shifted to an API-First model a few years ago. The second is Algolia, which is an API-First and has theorized this approach as the cornerstone of its business model.

Etsy’s path to API-First

Etsy's API-first design has revolutionized the way the company approaches its development process. By choosing to focus on the API level before integrating changes into the website, Etsy has been able to build reusable API components, reducing complexity and avoiding repeated logic between platforms.

Their code was causing a problem as it had to be implemented twice, once for their website and again for their mobile apps. This meant that all the code that was built for the website had to be rebuilt in their API to be used by their iOS and Android apps. To solve this problem, they switched to an API-first design approach.

API-first design means building everything on reusable API components that can be shared between platforms. Etsy had to rebuild its API framework from scratch to support this approach.

They also introduced concurrency handling, strong typing, and code generation into their API design:

• Concurrency handling allows multiple requests to be processed at the same time.
• Strong typing means that data has specific types, like numbers or strings, and this helps avoid errors.
• Code generation creates code automatically from templates, which saves time and helps reduce errors.

The Etsy team created a new API framework from scratch, called version 3, which uses perspectives and services to clarify data access rules and separation of concerns. They also use typed parameters and typed results to improve performance and maintain data integrity. A typed parameter means that each parameter is specific, such as a string or a user ID. A typed result means that the output of an endpoint is specific, such as a listing card.

Finally, they developed an API compiler to generate client code in PHP and JavaScript automatically. That means that code is created automatically based on the endpoint declaration files. The Etsy team checks if the compiled routes and client code are up to date via Jenkins, which is part of their continuous deployment process.

Algolia’s API-First approach example

Among the Top 100 API-First featured in our Report, Algolia has made the API-First approach the centerpiece of its product and its communication. What defines this approach is an API:

• Designed for developers: Algolia's API is designed with the needs of developers in mind,. It’s API is simple and intuitive, making it easy for developers to get started quickly. The API is well-documented, with clear and concise documentation that makes it easy to understand how to use each API endpoint.
• Flexible and scalable: The API can be used to build a variety of search applications. It is also built to handle high traffic volumes and is designed to be scalable as the needs of the application grow.
• Easy integration: there is a wide range of applications and platforms, including web, mobile, and desktop applications. The company offers a range of developer tools, such as libraries and SDKs, making it easier for developers to integrate the API into their applications.
• Emphasis on performance: Algolia's API is designed to provide fast and responsive search results, with a focus on performance and reliability. The API is optimized for speed and is designed to handle complex queries and large data sets.

And on the business side, this implies creating a marketing message aiming at:

• A value proposition based on the ease with which the API is implemented and the speed at which the API processes and executes searches.
• Pricing based on a pay-as-you-go model, with a free tier.
• A developer portal made to optimize API adoption, with key features including quickstart and tutorials, guides based on specific use cases, and API documentation with code snippets and examples, just missing a “Try it out” option.

Final words

Anyone who has experienced implementing an API-First strategy inside an organisation will tell you that it takes time and resources. But the result is worthwhile. It helps save time, prepare your API and product to scale, and offer APIs that are aligned with the needs of your customers. At each stage of the implementation process, the API-First approach helps unleash new opportunities for any type of company dealing in APIs or data. This applies as much to the design stage, which requires reverse thinking to view your API as a product, as to the monetization stage, which requires a value proposition and business model based on what this API can do and the value it brings.

Keep in mind that behind all the various (and variating) definitions of API-First you will read, there is one constant key idea: designing APIs that actually help your users or consumers, are easy to implement, and are displayed on developer portals made to meet their requirements.