Starting a new API project can be a daunting task, especially if you are not sure where to start. There are a number of different approaches you can take, but one of the most popular approaches is to adopt an API First approach, which can help to improve your chances of success.

What is API First?

API First is a term and a concept that gained popularity during the brief Digital Transformation hype train of 2019-2021, most importantly it is also a term that is often used in conjunction with the term API Gateway and API Management.

API-first is a product-centric approach to developing APIs. It views the role of APIs as discrete products, rather than integrations to be subsumed within other systems. The overall goal is to produce a set of modular, interoperable APIs which, when combined, create an API platform that will help to foster and drive further innovation.

The term API First is often used to describe the process of designing and developing an API, however, the truth is API First is more than just developing an API. It is a business process that is designed to help organisations to think and focus on the business value of the API and how it will be used by the consumers of the API.

Originally, the term API First was coined by Kin Lane in 2011, when he was working at API Evangelist. Kin Lane is a well known API Evangelist and has been working in the API space for a number of years. He has been instrumental in helping to shape the API industry and has been a strong advocate of the API First approach.

At its core, API First helps to focus on 3 main aspects or pillars of the business organisation and how they can be improved by adopting an API First approach. These three pillars are:

• Business

API First is help organisations to embrace APIs at the business level, and to understand that while APIs are not the only important aspect of business software, they are the products that you create, manage, sell, measure, recombine, and retire. API First means that if a product in your organisation does not have an API, it essentially does not exist. APIs are the connective fabric that allows your organisation to create value and to be able to quickly adapt your value chains in response to internal and external feedback.

• Organisational

API First means that all teams embrace the fact that whatever they create has to be delivered through an API. It also means that teams understand that API quality establishes an upper threshold for product quality: No matter how good your service or product is, if it is delivered through a bad API, this substantially diminishes the quality of the product. Essentially, the organizational aspect of API First is to understand that as a result of digital transformation, organizations become easily reconfigurable meshes of API-delivered services, and anything that compromises this vision is problematic for long-term success

• Technology

All products are designed with their API in mind. The API is the first User Interface (UI) in the sense that it defines and limits the kinds of interactions that a product supports. Concrete UIs that are later built may only use parts of the API, or they may combine various products into one UX, but in terms of pure product capabilities, the API is the single source of truth. This is why designing and discussing APIs should be done before implementation starts. Early prototypes with possibly limited functionality should be produced as quickly as possible, but even before that sitting down with potential users and discussing design options and preferences can be extremely valuable.

With the right iterative approach the API can grow in an evolutionary manner (adding more features over time as they are requested). As a general guideline, always discussing designs before implementing them helps with creating more user-friendly APIs. Since the API is one of the essential aspects of all products, documenting it becomes important. While the level of documentation depends on intended audience size and how much the Developer Experience (DX) of the API is thought to be a deciding factor, documentation should be seen as an essential part of each API. Structured documentation such as API labels can help to document APIs in a more structured way, so that growing and evolving API landscapes are easier to understand and manage.

Need help with API Development?

threenine.co.uk can help you with your API Development. We have experience in building APIs for a range of clients, from small startups to large multi-national enterprises. We can help you with your API Development, whether you need a new API or need to improve an existing one.

Connect today

API First Principles

These concepts and pillars are the foundation of the API First approach and are the guiding principles that start to guide the organisation to start thinking about APIs as products and how they can be used to improve the business, put them into practice.

The core three core principles of API first to focus on are :

• API as first UI

Every product gets designed with its API in mind. The API is the first UI in the sense that it defines and limits the kinds of interactions that a product supports. Concrete UIs that are later built may only use parts of the API, or they may combine various products into one UX, but in terms of pure product capabilities, the API is the single source of truth.

• API before Implementation

Designing and discussing APIs should be done before implementation starts. Early prototypes with possibly limited functionality should be produced as quickly as possible, but even before that sitting down with potential users and discussing design options and preferences can be extremely valuable. With the right iterative approach the API can grow in an evolutionary manner (adding more features over time as they are requested). As a general guideline, always discussing designs before implementing them helps with creating more user-friendly APIs.

• API Documentation

Since the API is one of the essential aspects of all products, documenting it becomes important. While the level of documentation depends on intended audience size and how much the Developer Experience (DX) of the API is thought to be a deciding factor, documentation should be seen as an essential part of each API. Structured documentation such as API labels can help to document APIs in a more structured way, so that growing and evolving API landscapes are easier to understand and manage.

Adopting the API First approach

The above core principles will help guide you to start thinking about APIs and how they can be used to help your organisation achieve its goals. The next step is to start putting them into practice. The best way to do this is to start by creating an API First Strategy, and adopting an API First mindset. There are a few key concepts to consider and always put at the forefront of your mind when adopting an API First approach.

1. APIs are Products

Developing and publishing an API may at first seem easy. However, what is truly difficult is actually preparing an API for public consumption. That’s the difference between merely creating APIs and treating them as products.

An API-first approach requires you to think about:

• how developers will interact with your API
• how you’ll educate them on its functionality
• how you’ll maintain it over time
• which tools to use to build the API
• how you’ll adhere to standards of compatibility, security, and simplicity.

When a company builds a product, it must meet industry standards. For APIs, this means practicing foundational software design and development cycles that deliver a quality software product. Product development includes upfront design and specifications, peer programming, technology choices and programming languages support that match the API’s goals, the decision between cloud and on-site, testing, and user research.

2. Foundational Design

API-first design requires organisations and developers to think about APIs from the very beginning. The API should be designed and developed first. This means that the API is the first user interface (UI) in the sense that it defines and limits the kinds of interactions that a product supports.

Traditionally, organisations have focused on the user interface (UI) and user experience (UX) of their products, before thinking of the API, and the API is often an afterthought, and worse its design is primarily driven by the needs and requirements of the User Interface. This is a massive mistake, and often leads to poor quality APIs

API-first development treats APIs as the foundation. Instead of pre-built or opinionated software solutions or experiences, it ensures that all of a platform’s functionality is accessible to you through the APIs.

3. Team Collaboration

API-first development is more than just technical standards. It’s a way of working and collaborating. Rather than just being concerned with the specifics of each API, an API-first approach is more about looking at your teams and operations that surround those APIs.

Achieving an API-first environment requires strong leadership from a product manager who is both knowledgeable about APIs and equipped with sufficient technical skills. It also requires skilled developers. Although most enterprise developers maybe good at delivering exceptional end-user experiences. It is a completely different skill set to creating good engineering (or developer) experience (DX). You need a customer success function to help with implementation and support to field ongoing queries and user feedback.

4. API Contract

Creating open and accessible APIs, companies can reuse, redeploy, and share functionality easily. But that’s easier said than done. One way to promote re-usability is through consistent API description language. Specifically, this creates a contract dictating how an API is supposed to behave. Establishing a contract involves spending more time thinking about the design of an API and often involves additional planning and collaboration.

API First is not easy

Adopting an API First approach is not easy, and it is not a quick fix. It is a long term strategy that requires commitment and dedication. It is a strategy that requires you to think about APIs as products and how they can be used to help your organisation achieve its goals.

The API First strategy requires you to think about APIs as end products and how they can be used to help your organisation achieve its goals or generating alternative revenue streams and enhancing existing product portfolios. This requires you to think about the business value of the API and how it will be used by the consumers of the API.

Business and technical leaders need to embark on API-first transformations with their eyes wide open. The skills and mindset required to succeed are different from those needed for traditional software development. The API-first approach requires a different way of thinking about software development and the role of APIs in the business.

Corporate cultural change

The key, and often overlooked aspect of the API First approach, is that it often requires a complete cultural change within the corporate approach, in that it requires thinking of your IT platforms not as a competitive advantage or transformation but as fully fledged additional products and services that your organisation offers.

The concept shares some principles with the API Economy, where APIs unlock new sources of value and more importantly additional revenue. It’s a holistic view of APIs as building blocks to create new products, favouring modular, reusable APIs over larger, monolithic APIs.