Guide to API-first
APIs, or application programming interfaces, have been around almost as long as modern computing. They emerged decades ago as a means to let disparate software applications communicate. And they still fulfill that role today, working invisibly in the background as our computers, phones, and smart devices connect to each other.
But APIs have evolved beyond the role of mere interface. In the past decade, they have become the building blocks of modern software and business. Whether at tech pioneers like Amazon.com and Netflix or century-old grocery chains and federal agencies, organizations are using APIs to offer new services externally and deliver efficiencies internally.
The growth of APIs reflects a new reality: Technology users demand experiences that span multiple devices. They expect their data and services to be instantly available and shareable across platforms. That means every business is effectively a software business, whether it's serving external customers or internal employees.
“As the connective tissue linking ecosystems of technologies and organizations, APIs allow businesses to monetize data, forge profitable partnerships, and open new pathways for innovation and growth.”
What is API-first?
API-first, also called the API-first approach, prioritizes APIs at the beginning of the software development process, positioning APIs as the building blocks of software. API-first organizations develop APIs before writing other code, instead of treating them as afterthoughts. This lets teams construct applications with internal and external services that are delivered through APIs.
An API-first company is an organization that has adopted the API-first development model.
How API-first works
For an organization to adopt an API-first development model, they need to prioritize APIs, recognize the role of public, private, and partner APIs in organizations, and understand the API lifecycle and the tooling needed to become API-first.
The API-first approach: prioritizing APIs
The most farsighted companies take an API-first approach to their software development. Before writing a single line of code, developers, in partnership with the business, first design or build the API. This ensures the underlying app can seamlessly connect with internal and external applications. Doing so expands the app's capabilities and makes it accessible to partners and end-users.
Being API-first means prioritizing the APIs that support your application and focusing on the value they can deliver to your business, rather than just scrambling to deliver a single application and creating an API as an afterthought. This forward-thinking approach allows the application to be adopted by different parts of the business for multiple uses, through the API.
APIs are not one-and-done projects. APIs are key building blocks that need to be maintained and improved. Companies are recognizing this and building teams to support it.
Private, partner, and public APIs
When people think of APIs, the first ones that often come to mind are public APIs from companies such eBay and Stripe. These APIs have helped millions of small businesses grow and created powerful tech platforms worth hundreds of billions of dollars.
But it is private, or internal APIs, where software developers devote most of their efforts. In fact, 58 percent of the APIs that developers work with are for internal use only, according to Postman's 2022 State of the API report, which surveyed over 37,000 API professionals.
Private APIs allow different applications, many of them stored in the cloud, to share data and services, and deliver actionable insights. Much of this can be done automatically, providing visibility across the organization for employees of every rank.
Once built, private APIs can be reused throughout the business, offering faster delivery and saving valuable developer resources.
As the needs of the organization expand and require interacting with business partners, partner APIs come into play. Partner APIs allow organizations to share their APIs with just select users and customers, offering opportunities to collaborate, create business partnerships, and gather targeted feedback. Partner APIs constitute 27% of organizations' APIs, according to the State of the API report.
Public APIs, APIs that are openly available on the web to all, account for about 15 percent of organizations' APIs, according to the State of the API report.
Altogether, how much effort are organizations devoting to APIs? Some 51% of developers say that more than half of their organizations' development effort is spent on APIs.
The API lifecycle
A well-defined API lifecycle is essential for taking full advantage of operating on an API platform and being able to effectively govern hundreds or even thousands of APIs across different teams.
Having a shared understanding of what the API lifecycle is across your organization, and possessing a common vocabulary for describing it, will help your teams get on the same page when developing APIs with greater productivity, quality, and governance needed to drive your enterprise.
We've broken up the API lifecycle into eight stages, based on the most common steps we see across Postman's global users. Depending on the type of API, and whether it is new or existing, your team may have different entry points in the lifecycle .
API platforms
API platforms are software systems with integrated tools and processes that allow producers and consumers to build, manage, publish, and consume APIs. They're a key enabler of API-first, and they have four key components:
Tools for the API lifecycle, including an API client, API design and mocking capabilities, API testing and automation, API documentation, and API monitoring
Collaboration capabilities for producers and consumers, including an API catalog and API workspaces
Governance capabilities for operations, architecture, and security teams, such as API security and observability
Integrations with the software development lifecycle, including source code management, CI/CD, cloud/on-premises infrastructure and application performance management
Why API-first?
Adopting an API-first development model affords significant benefits for both developers and organizations.
The value of API-first for developers
An API-first approach not only produces more powerful, resilient software, it does so in less time. It makes developers' jobs easier, allowing them to work in parallel and spend fewer hours debugging others' code.
Developers can focus on innovation rather than recreating existing software. And APIs allow them to choose the technologies, platforms, and programming languages that they want to work with.
Ultimately, this means developers at API-first companies are more satisfied. In our State of the API survey, at least 75% of respondents agreed that developers at API-first companies are happier, launch new products faster, eliminate security risks sooner, create better software, and are more productive.
API-first also allows non-developers to build apps. About half of the people working with APIs come from roles such as business analyst, product manager, and CEO, according to the State of the API report. This trend is vastly expanding the world of available services and software.
As API platforms evolve, people with no prior knowledge of code will increasingly be able to build common apps, run tests and integrations, and transfer data.
The value of API-first for businesses
With APIs becoming the building blocks of modern software, the benefits of adopting an API-first approach are many. This is especially true for large enterprises. Here are just a few of the advantages that API-first confers:
Increasing developer productivity
When organizations adopt an API-first development model, developers and product teams see an increase in productivity through faster collaboration across the entire API lifecycle. In this approach, developers establish well-known workspaces where API work is centralized, ensuring they possess artifacts, documentation, mock servers, environments, tests, monitors, history, and everything else team members need. Repeatable processes are established that optimize the design, development, deployment, and operation of APIs and microservices.
Improving software quality
The value of API-first for developers—enabling developers to produce more powerful, resilient software in less time—translates directly to improved quality. With an API-first approach, operations, quality, and security engineering teams all see an improvement in quality because bugs don't reach production, quality engineers find issues faster, and security engineers collaborate for airtight security earlier. And, with API-first approach, these foundational teams are able to collaborate directly and effectively with development teams.
Simplifying compliance and governance
Architects are able to organize and manage the entire API landscape in a consistent way through the Private API Network and they are able to inject design and governance rules in the design and development stage.
In an API-first approach, you have the discoverability and observability present as a default part of your operations, reducing the friction associated with responding to regulatory requirements and inquiries.
API-first also provides visibility across your operations, helping you understand where consistency exists or doesn't exist in the design of an API. API governance is about being able to understand the state of your complex enterprise system and having the control and influence to make updates, guide, and realize the change you need to move in the right direction.
Providing a solid API security perimeter
An API-first security perimeter is much more effective than firewalls and existing application security practices alone. Every API and microservice has a security collection that is centrally defined by security experts, but then also applied as part of the regular API development lifecycle by developers.
Even the simplest of APIs are forced through the minimum security scanning and evaluation as it is being deployed or changed with each version. Security is consistently applied across all APIs used by teams, no matter what the application is or how long the API will be used by consumers.
API-first as a competitive advantage
Enterprise organizations across every business sector are waking up to the importance of APIs. However, it is the ones who have embraced API-first that are leading and shaping business around the globe today.
When an API-first approach is adopted in concert with an API platform, the advantages multiply. At this point, it isn't whether you want to do APIs, it comes down to whether you are API-first.
Are you an API-first company?
API-first companies answer yes to all the following questions:
- Do you have APIs to operate most of your data?
- Do you make APIs available to your customers and partners?
- Do you know how to organize and discover your APIs?
- Do you have standardized processes to build APIs?
- Do your APIs meet regulatory requirements?
- Do you know the security risk to your API perimeter?
If you didn't answer yes to all of these questions, read on to learn how to become API-first.
5 steps to become API-first
Here are the initial steps to becoming an API-first company:
- Take inventory of APIs: Inventory your databases, applications, and services—understand exactly how many APIs you have, and where you lack APIs. Create a comprehensive list that includes not just what these tools are, but also what they do and who uses them. This detailed inventory will be invaluable for your API-first journey.
- API production insights: Understand your organization's approach to producing APIs—identify where standard processes exist, and where they don't. Once you've identified where standard processes might be missing, encourage your teams to develop guidelines for those areas to ensure consistency in your API production.
- Define boundaries: Define your business domain boundaries and map your organizational structure to those boundaries. This mapping process can also help you spot overlaps or gaps in your organizational structure and improve communication and collaboration among teams.
- API platform adoption: Adopt an API platform and ensure it integrates seamlessly with your existing tools and technologies. This will make the transition smoother for your teams.
- API-first training: Train your engineering, DevOps, and product management teams on API-first. Consider creating a program that includes workshops, resources, and even mentorship to continuously enhance your teams' API-first skills. This will keep them up-to-date with the latest best practices.
Other common comparisons related to API-first
API-first vs. API design-first
API-first prioritizes APIs at the beginning of the development process, positioning APIs as the building blocks of software. This lets teams construct applications with internal and external services that are delivered through APIs. API design-first is a development model that supports the API-first strategy, in which the APIs are designed before they are implemented, with input from stakeholders across the business. This produces a human- and machine-readable contract and can create a better developer experience.
API-first vs. code-first
In API-first, developers start by designing and building the API in partnership with business stakeholders—before writing a single line of code. This helps ensure the underlying app seamlessly connects with internal and external applications. Alternatively, a code-first approach starts with prototyping what the full application will be, and gradually shaping it over time. This could include building out the API, which then needs a full design of its own. A code-first approach can help prototype an idea, including the API, UI, and other components for a full project. However, many companies may not discard these rapidly built prototypes, which may include poor design choices that deliver a subpar developer experience. API-first, on the other hand, enforces strong design principles from the beginning.
Navigating the paths to API-first
API-first will save your developer team pain and suffering, and save your organization time and money. But there are several valid routes to API-first. Which is the right one? Some of the most notable are:
Design-led
For many, this is 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.
Code-led
You prioritize coding the API before you code the applications that use it.
Prototype-led
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-led
You run your existing API through a proxy or Postman Interceptor, and generate a collection based upon existing traffic.
Collection-led
This involves good old-fashioned handcrafting of a Postman Collection for an existing API and then generating an OpenAPI from that collection.
The API-First Transformation is here
Kin Lane's book The API-First Transformation shows business leaders how to create an API-first strategy, assemble the right technology, and put solutions to work.
API-first on the Postman Blog
2024 State of the API report is here!
Discover key API trends from 5,600+ devs and API professionals in Postman's annual report.