Application Programming Interfaces (APIs) have long been regarded as the building blocks for any company striving to succeed in the digital economy. Their popularity and usage are undeniable — API traffic is now dominating the internet, increasing from 47% in 2014 to 83% in 2019. So, with the wealth of information on the importance of APIs as catalysts for delivering digital experiences and proof of their actual web dominance, why are companies still talking about digital transformation? Why is the digital transformation urgency increasing? Why is now an important time for non-API-first companies to reflect on their approach to API delivery?

Are companies still talking about digital transformation?

The simple answer is yes. According to MIT Sloan Management Review, companies are​ estimated to have spent​ $1.2 trillion on digital​ transformation efforts​ in 2019 and 2020, yet only 13%​ of leaders say their​ organizations are ready​ for the digital age.

Why is the digital transformation urgency increasing?

The COVID-19 pandemic shifted the digital-maturity goalposts for many companies and is accelerating the urgency for digital agility. The rules for success have changed and are ever more reliant on embracing the power of digital models to create new business value and immersive experiences. For many companies, the current conditions present a point of introspection as they look to grasp the opportunity to carve out revenue streams and capitalize on the potential of a business-to-business (B2B) market that is set to triple to $21 trillion by 2027.

Why is now an important time for non-API-first companies to reflect on their approach to API delivery?

Although many traditional companies, whose success predates the web, can have years of API delivery under their belt, the shift to an API-first driven enterprise causes much internal debate. In many cases, such companies’ initial approach to APIs was merely a by-product of launching mobile app and web portal channel experiences. The ability for these non-API companies to realize the full potential of APIs, as an unbundled entry point into their unique business-value offering, was never brought into sharp focus. Such transformational challenges can often be attributed to the organizational structure itself, meaning the delivery of newer digital experiences happened without reassessing their value proposition in the digital age and was blinded by technology.

Fragmented approaches to API delivery have led many companies to become fearful of the API chaos emerging within their walls, paralyzing their digital evolution. The scourge of undocumented RESTish APIs propping up many internal system integrations has emerged as a common theme associated with such challenges.

Self-reflection question: If you’re building APIs that do not conform to an industry-standard API specification, then are you in control? If you claim to be, then how much is that control costing your teams and eating into their velocity per delivery cycle?

Calming API Chaos Blog Series

In this first of two posts, I explain what API specifications are and share some reasons why they can be leveraged for more than just documentation across the API lifecycle. In part 2, I look at how API specifications can “add method to the madness” and the practical benefits they bring within a digitally transforming company.

The main benefits of API specifications include:

• Enabling consistency for customers
• Addressing technology debt without breaking your contracts
• Enhanced security and agility
• Reduced communication and knowledge sharing burden

It is never too late to benefit from API specifications regardless of your phase of digital metamorphosis.

What Are API Specifications?

In general terms, a specification is a technical document that tells you how something works. API specifications are no different and have the added advantage of being both human and machine readable.

There are varying API specifications in use within the industry. Two specifications that have gained popularity in recent times due to their vendor-agnostic approach and rich tooling ecosystems are:

• OpenAPI Specification: Defines a standard programming language-agnostic interface description for REST APIs.
• AsyncAPI: Defines and annotates the different components of a specific event-driven API.

Using an API specification can be helpful to standardize how data is exchanged between services, but having a more holistic view of the benefits of API specifications can help scale API delivery within the enterprise.

More Than Just Documentation

API specifications are for more than only documenting what your API looks like. Approaching the curation of specifications to produce consistent brand-aware APIs empowers companies to reduce delivery waste and speed up their time to market.

Using familiar standards with their rich ecosystem of tools reduces the consumer’s “Time to First Hello World,” thus speeding up the ingestion of the API value into their own customer value chain. Applying standards uniformly across all exposed APIs by leveraging an API style guide and common governance model creates a healthy sense of “déjà vu” for consuming developers, allowing them to focus on their jobs to be done and not be distracted by quirky implementations.

Using an API specification can help automate many stops along the API lifecycle, including client and server code generation, mocking an API’s implementation, test automation, telling the story of the API, and more. Such automation reduces so much waste from the DevOps cycles on both the producer and consumer sides of the API.

Leveraging specifications within an API-first design approach is recommended and allows two key questions to be asked early in the process:

1. Are we delivering the API right?
2. Are we delivering the right API?

These questions should get answered by having cross-functional stakeholders participate upfront before emotional attachment forms around the “thing” you are building, thus protecting you from a potential sunk cost fallacy. The automation of uniformity and governance checks, which analyze the “thing,” ensures it meets brand consistency, security requirements, and appropriate developer experience criteria.

Tip: Ask the above questions early and often!