API-first is a product-centric approach to developing APIs. It views the role of APIs as discrete products, rather than integrations subsumed within other systems. The overall goal is to produce a set of modular, interoperable APIs which, when combined, create an API platform that fosters innovation.
The concept shares some principles with the API Economy, where APIs unlock new sources of value. It’s a holistic view of APIs as building blocks to create new products, favouring modular, reusable APIs over larger, monolithic APIs. With API-first, APIs are treated as their own product, not just as a piece of integration middleware. This makes them a strategic play, rather than tactical.
API-first emerged alongside the growth in popularity of the microservices API design pattern, and is part of the overall paradigm shift towards favouring loosely coupled service-oriented architectures.
Understanding of API-first within the API industry
The term API-first doesn’t appear to have a universally understood definition. When Postman, in their 2021 State of the API Report, asked participants what API-first meant to them, the top two answers were:
- “Defining and designing APIs and underlying schema before developing dependent APIs, applications, or integrations”, with 42%
- “Developing APIs before developing applications or integrations dependent on APIs”, with 31%
While these two definitions seem similar, there’s a subtle difference. The first prioritises API design as part of an overall system development life cycle, whereas the second treats APIs as building blocks on which other systems are developed.
This difference is explored by Stoplight in their blog post API-First vs API Design-First: A Comprehensive Guide. They find that the two terms are “often used interchangeably”, summarising the difference as “API-first is about putting APIs front and center, API design-first is about the process of creating the API itself”. In this regard, API design-first can be seen as a subset of API-first, and as such can be used as part of an API-first approach.
When comparing the results of the State of the API Report with the opinions of various API industry blogs, the report respondent’s view of API-first is more aligned with the industry blog concept of API design-first. This suggests that, while organisations view APIs as a priority, most are using them as tactical solutions rather than as an API product-led strategy.
Benefits of API-first
There are numerous benefits to adopting an API-first approach. These are aligned with the typical benefits often associated with APIs. But with API-first, the benefits are amplified.
Postman’s State of the API Report noted that those seriously pursuing an API-first approach produce APIs faster, deploy more frequently, suffer fewer failures, and recover faster when failure occurs. Similarly, Google Cloud’s Digital Transformation Report states that the majority of large organisations are using API-first strategies, and that those who align more with the approach gain the greatest benefits, reporting “faster innovation and greater value from business partnerships”.
Developer experience
In general, APIs accelerate the development process by providing simplified access to data and functionality. Development teams use the APIs to leverage the value the APIs provide, and avoid having to implement the functionality themselves. API-first expands upon this general trait, by focussing on APIs as building blocks. Consumers can pick and choose the blocks that they need, saving them time and effort.
By focusing on the design of APIs and building them with a product mindset, the resulting APIs provide a better developer experience. This is particularly relevant in the context of API platforms built with the API-first approach. The ability of a modular set of APIs to operate cohesively is beneficial to consumers, especially when compared to disparate APIs which are not designed in this manner.
Consistency is important to the overall developer experience. Developers face fewer difficulties in consuming an API when data is provided in common formats, using common protocols and processes. The API-first approach accomplishes this by understanding that APIs are part of an overall platform where interoperability is crucial. Consistency is achieved by using assets such as style guides, which enable API development teams to build APIs which operate harmoniously.
Flexibility
The API-first approach treats each API as its own product. This decoupling gives the APIs flexibility in how they are designed, developed, deployed and maintained. It allows organisations, and the teams building the APIs, freedom of choice when choosing the API’s technology stack. It’s even possible to vary tech stacks across APIs, if there’s a desire to do so.
The decoupled nature of API-first helps to reduce dependencies. This allows APIs to grow, evolve and be refactored with less of the complexity inherent in larger, monolithic systems. This is also true of the infrastructure required to host the APIs, as each API can choose its own infrastructure, specific to its needs. This fits well with modern deployment approaches, such as containerisation, where individual services are sized as needed, and scaled on demand.
Interoperability
Adoption of standards is an important aspect of an API-first approach. Standards help to promote compatibility, interoperability and overall utility between systems. This shares similar principles with the economics concept of a network effect, which describes how the value of a system increases as the number of compatible users also increases. When API providers adopt common standards, such as OpenAPI Specification (OAS), it enables consumers to harness the ecosystem of third party tools and systems which are also compatible with those standards.
The benefits of standardisation apply to both the provider and consumer. For example, an API provider can use their OAS document to automate the creation of documentation. Whereas API consumers can benefit by using an OAS document to automate the creation of API client Software Development Kits.
When used appropriately, OAS documents offer a single source of truth. Sometimes referred to as a contract, OAS documents promote collaboration by acting as an agreement between parties. To ensure that they are fulfilling their side of the contract, API providers can use the OAS documents as part of an automated testing process, to identify errors earlier in the API development lifecycle and prevent them affecting consumers.
Innovation and opportunity
Organisations often have systems which contain valuable data and functionality. However, unless these systems are accessible, efforts to realise the opportunity of these systems will be hampered. APIs can help to unlock this trapped value, creating new business models and revenue opportunities.
Furthermore, an API-first approach will increase the chances of success by creating APIs which are documented, consistent, accessible and reusable. By treating the APIs as their own products and dedicating sufficient time and resources to their design, the API-first approach can cater to a wide range of consumer use cases. This increases opportunities for collaboration between business units within the organisation, as well as external consumers such as clients, partners and other third-parties.
API-first can assist organisations with implementing omni-channel strategies. The headless nature of APIs is a good fit for this, as the various systems and applications which comprise an omni-channel approach can use the APIs to get the data they need in the way they need it. With API-first, the APIs serve as a composable foundation on which omni-channel solutions can be built.
Challenges of API-first
Following an API-first approach is not all positives. There are some challenges too.
Culture change
Adopting an API-first approach could be difficult for organisations where executive-level support is lacking. To adopt API-first requires a change in mindset, to treat APIs as their own products. Without this, APIs will remain a purely tactical play, limited in scope and lacking the necessary strategic thinking. Executive level support is needed to ensure that any necessary changes in process, staffing and culture have the required level of support to succeed.
Technology diversity
Given that the API-first approach treats APIs as independent products, each API has freedom of choice over its technology stack. This isn’t necessarily a bad thing – using the right technology to solve a problem can be beneficial in many ways. But it can also lead to technological divergence across APIs. In such a situation, a broader skill set is required by the developers who build and maintain those APIs. Therefore, an organisation’s staffing decisions will affect the flexibility and cost of the workforce, as well as the development time and overall quality of the outcomes.
Security
A system cannot be hacked if it cannot be reached. This is why some critical systems use the air gap security measure, ensuring that they’re not reachable over a network. Unfortunately, for the API-first approach, and APIs in general, the air gap approach is not possible – an API has no purpose without consumers. The purpose of APIs is to facilitate integration, so they must be accessible over a network, making them vulnerable to attack. In addition, as the number of APIs increases, so does the attack surface. Of course, there are many measures which mitigate the threats posed to APIs, but organisations must be aware of them and take appropriate action.
Security concerns can be exacerbated by technology diversity, where an increase in the number of technologies makes the task of securing the system more onerous.
Governance
Governance is important in the contexts of technological diversity and security, where it provides oversight and direction on the challenges faced, and enforce standards across the API platform. Without adequate governance, the whole API-first concept is undermined.
As with any scenario where one system consumes the output of another, it’s important that the consumer can rely on the provider. Otherwise the integrations between consumers and providers will be brittle and subject to failure when change inevitably occurs. This means that it’s important to adopt a robust release process and approach to versioning, as well as clear policies on backwards compatibility.
Learn how a Swiss marketplace giant managed to solve all of its challenges with Tyk:
Read case study
Adopting an API-first approach
Tyk has produced a white paper called Approaching Your API Strategy. It provides five key disciplines for a successful API programme:
- Define your API strategy: The overall strategy must be executive-driven, with clear objectives that are communicated often. This ensures that the teams building the APIs have a holistic understanding of the ambitions of the API programme, the purpose of the APIs and the market they are serving.
- Create organisational alignment: Use a product-centric delivery model, cross-functional team ownership and a supportive training programme to ensure that the teams delivering the APIs are self-reliant, have the necessary skills, feel a sense of ownership and are empowered to deliver.
- Manage your API programme: Effective governance is crucial if the API programme is going to succeed. Not only from a high-level API portfolio management perspective, but also regarding the individual APIs themselves. The APIs must be designed to meet the needs of the market, managed to ensure quality of service, and altered as market conditions or the overall strategy changes.
- Focus on API adoption: An API with no consumers produces no value. Therefore, it’s crucial to ensure that API consumers are provided with an end-to-end process which enables them to easily discover, onboard and begin using the APIs.
- Accelerate your API programme: The API development lifecycle relies on a cross-functional effort, involving architecture, security, infrastructure, engineering, programme management and developer relations teams. Using a product-centric approach places these different specialisms within the same team, allowing them to fully own the delivery, minimise obstructions and increase delivery cadence.
Alternatives to API-first
If API-first exists at one end of a spectrum, then code-first exists at the other, with API design-first somewhere in-between.
Code-first
The code-first approach, sometimes known as integration-first, treats APIs as tactical implementations. APIs are built to serve a particular purpose or single use case, such as connecting two systems within a larger overall project, or as endpoints which power a user interface. Priority is given to making sure that the API is correct for the given implementation, rather than considering how it could be used on a wider basis.
Due to its reduced scope, the code-first approach is typically the fastest way to produce APIs and is also the least burden to maintain. However, this also limits how much value the APIs provide. In their Digital Transformation Report, Google Cloud states that “a healthy minority of enterprises still think of APIs in integration-first terms. This mindset can block these organisations from many of today’s most important business opportunities and impede their ability to adapt to new opportunities that may emerge in the future”.
Finding and exploring new opportunities is considered out of scope for code-first APIs. Once built, code-first APIs typically don’t evolve unless required to do so by the systems they’re connecting.
API design-first
As mentioned previously, the principles of API design-first can be equally applied to API-first, and as such can be considered a subset of it. It’s a design-led approach which produces a number of useful artefacts that are beneficial to both the provider and consumer. Items such as API documentation and style guides, which can be considered out-of-scope in API code-first implementations, but are vital in enabling wider API consumption and interoperability.
Due to its focus on design, API design-first has a larger up-front effort when compared to the code-first approach. But this is not without reward, it produces APIs that are more consistent, serve more use cases, have a better developer experience, and are more adaptable to future change.
When compared to API-first, the difference is in the extent of strategic thinking. API design-first has the primary goal of designing APIs correctly, rather than producing APIs to build an API platform ecosystem. The additional levels of API governance and portfolio management found in API-first produce a highly cohesive and functional API platform.
Conclusion
API-first is the natural choice for organisations who want to make APIs a central part of their overall strategy. Its holistic approach to APIs doesn’t end with the design and build, but goes on to create API platforms with the goal of serving as building blocks to a multitude of consumers. Strong governance practices allow the API programme to run efficiently and to evolve, keeping it aligned with organisational objectives and consumer needs.
Implementing API-first has larger up-front and ongoing costs than other API approaches, but also results in larger benefits – improved developer experience, technical flexibility, system interoperability, innovation and ability to realise opportunity.
However, API-first isn’t suitable for all organisations. Especially those who are content to use APIs in a tactical sense. But for those who are already taking a design-led approach to APIs, they are already embracing part of the API-first philosophy. For these organisations, the jump to API-first is more compelling, especially if APIs are prevalent within their organisation.
To start your API-first journey, check out our API management documentation.
