In part 1 of this blog series, I covered the growing urgency for APIs and their foundational qualities of success for any company striving to transform in the digital economy. I answered some fundamental questions on why the importance of APIs is still increasing and why now is an essential point of introspection for many non-API-first companies.

This week, after laying down the “why” of it’s so important, I’d like to go over a few principal benefits of having API specifications in place.

Benefit 1: Enables Consistency for Your Customer

Working from the outside in and focusing on north-south traffic, the obvious first benefactor from thoughtfully designed API specifications is the consumer. Consider the business value that products to be exposed out of the organization presents. They provide an optimal opportunity to hide internal complexity, protocol variations, and technical debt. The past does not dictate the future, so grab the opportunity to reinvent how your APIs will expose value.

It is normal in many enterprises for business capabilities to be spread across numerous systems within the IT landscape. Exposing business value in an unbundled manner via an external-facing API often involves multiple components. It also forces teams to deal with mission-critical systems that cannot change at the pace digital marketers often appreciate.

Figure 1: Simple on the outside can mean complex on the inside.

In Figure 1, the customer interacts with a single API and has no awareness of the underlying implementation. They send a request to the API, and it ensures the request reaches the correct location and returns the appropriate response. The orchestration could involve several protocol transformations, enrichment, and security negotiations. But all this effort is only worthwhile if the experience is simple, intuitive, and consistent for the consumer!

Getting to this point is already a great step. Maybe even the customer experience (CX) teams are beginning to understand the persona of the “developer” and the importance of the developer experience (DX). The need to have brand affinity across externally exposed APIs should be no less than any other product offered by the company.

Benefit 2: Address Technology Debt Without Breaking Contracts

Once an API contract is in place serving the business value and is sufficiently decoupled from system implementations, opportunities to simplify the landscape and/or address the technology debt become viable. This should be all possible without impacting the consumers of the upstream API products.

Figure 2: Systems removed from landscape without impacting external consumers

Addressing technology debt (code refactoring, software/hardware upgrades, etc.) and even system decommissioning within the landscape, as depicted in Figure 2, are possible. Just make sure not to break the external API!

The existence of the API specification gives peace of mind to both API delivery teams and underlying system teams. Assuming the appropriate test automation is in place, proving the success or failure of system overhauls becomes binary.

Benefit 3: East-West Transparency Improves Security and Agility

Getting the right balance between speed, agility, and security is arguably going to be the most important consideration companies must deal with continuously when delivering digital assets. API threats are increasing, and as companies move to full cloud or hybrid cloud infrastructure configurations, the over-reliance on network perimeter security becomes all too apparent. Proper Zero-Trust security for API infrastructure is not the responsibility of an API gateway.

Each API (or at least delegated to a service mesh) should have the ability to perform fundamental levels of authorization and security functions. Making an API gateway solely responsible for API security and validations while forgetting about safety on east-west traffic is a disaster waiting to happen.

The benefits of API specifications on the external edge of the IT landscape are directly applicable within the landscape. Immediate tangible benefits will emerge due to the increased discoverability, which will help address the blind spot caused by poorly or undocumented RESTish APIs (aka “spaghetti junction”).

Assessing the state (or cataloging) of the API landscape directly against the specifications in the code repositories (or via continuous integration tooling) provides immediate insight into the state of the integrations within the enterprise. Historically, this role was often played by API gateways which is both too late (waiting for API to be published) and assumes that all internal APIs will leverage a gateway for access (almost never guaranteed).

Internal API marketplaces are gaining popularity to promote reusability and a shared benefit approach to managing internal API artifacts. Marketplaces aside, having API specifications for your internal APIs brings real improvements by injecting quality early in the delivery cycle and promotes a better developer experience for internal development teams.

Benefit 4: Reduce the Cost of Knowledge Sharing

Knowledge workers are key to any organization, and every effort should be taken to reduce the cost of knowledge continuity. Having the right people on the team is crucial, but ensuring they can have the environment to contribute effectively is even more important.

The now infamous Jeff Bezos (AWS) mandate recommended teams expose all their functionality through service interfaces and that team communication must go through the same interfaces. Almost 20 years on, the concept still holds true, and API specifications offer the opportunity for companies to provide consistent self-service communication agnostic of the underlying technology choices.

API specifications are one of the best mechanisms for naturally expressing the integration capabilities you make available as a team toward others. Without them, a team falls back to home-grown documentation mechanisms, or worst still — none! Reduce the temptation of glass-box approaches; they will not be faster in the long run.

Common concerns and challenges that can arise:

• Difficulty in sharing API details with other teams — causing meeting-heavy culture and over collaboration.
• Time to onboard new team members increases — team-centric (or no) documentation.
• Risk caused by key team members leaving — knowledge leaves too!

Instead, let the specifications and tooling ecosystem that supports them answer many of the questions on behalf of the team. They should be regarded as the source of truth. Any unanswered question is best addressed by incorporating the answer into the specification or its virtualization.

Final Thoughts

Will API specifications solve all our challenges? Is it that trivial?

Of course not. The story of API-first and the supporting specifications must be told with a large pinch of realism, especially for more traditional and large organizations. API specifications are not magic wands. But, they do enable a consistent and empathetic approach that benefits customers and employees alike.

Take the opportunity to reap the benefits with your next API deliverable. If humans do not thank you, at least the machines can!