Designing the APIs that accidentally power businesses

In the last decade, every web application developer has become an API designer. But most organizations do not think of developers as API designers, nor do they think about APIs as a product of design — to the detriment of their developers’ productivity. With the rise of AI, there are more APIs than ever before, making this problem even worse.

In this article, I’ll talk about the often-neglected internal APIs that, more and more, accidentally power businesses and how organizations can get back on top of these APIs.

The (internal) APIs that accidentally power businesses

The APIs that often get attention are the APIs that organizations have intentionally built their businesses on. These are APIs like the Stripe API, the Twilio API, and the Instagram API — APIs that are crucial to companies’ product and go-to-market strategies. These APIs start with well-reviewed designs and go through many iterations of polish, curation, and documentation before they reach their consumer, the public.

Then there are the APIs that organizations have accidentally built their businesses on:

Front-end and back-end APIs. The rise of RESTful API design since the early 2000s means that web application front ends primarily talk to back ends via APIs.

Cross-service APIs. The rise of service-oriented architectures since the early 2000s means that software organizations are structured such that each team owns a set of services. These teams operate in an increasingly decentralized way, with individual teams designing their own APIs, rather than a small number of architects designing all APIs in a top-down way.

There are often more of these kinds of APIs than external-facing APIs. These internal APIs are often designed and owned entirely by developers.

Why design matters for internal APIs

Okay, you might wonder. What does it matter that developers are designing APIs that external users have never seen? Product managers and business owners never dug into the code, so do they really need to dig into internal APIs?

The issue at hand is that developer-driven design decisions affect both the ability to deliver a good user experience and the velocity of development (and thus the nimbleness of the business). And there is a tension between these two concerns.

From the perspective of an API user, the ideal API design has the most general possible functions. For instance, if you’re using a bank API, you ideally want there to be only one function for getting the balance for a user, one function for changing the balance, etc. If there are dozens of functions to call to get a bank balance, it becomes much easier to call the wrong one!

From the perspective of a developer, however, the easiest API to build for is the most specific. This is because the more specific a function is, the more a developer can optimize. For instance, the way to build the fastest possible banking app is to have the app back end send exactly the right information the app front end needs and no more. Internal APIs bias towards performance, meaning they are designed by the developer for ease of optimization, rather than for ease of consumption.

In the absence of other forces, developers will bias towards delivering a good immediate user experience rather than towards longer-term development velocity, or even reuse of an API for platform purposes.

Harness the power of developer-driven design

There are two ways to look at the world of APIs we now live in. If we look at this world from the lens of top-down API design, we can bemoan the chaos and API sprawl that has befallen us and continue trying to get in control in a spec-first way.

But there’s a more empowering alternative, one where we accept the developer-driven nature of API design and embrace collaboration. API design does not have to be fully top-down, architect-driven, or bottom-up developer-determined. What if API design were, instead, a collaboration?

Here is one model of what collaborative API design looks like in a developer-first model:

An API developer designs an internal API for a specific purpose, getting feedback from the immediate consumer and fellow API developer. These designs are not just static documentation but may be enhanced with richer information from tests or mocks.

As the API gets more usage, the developer gets more feedback and updates the API.

Previous versions of the API get stored and documented; the reasons for updating the API are clear to everyone.

The API evolves in tandem with a “living design,” allowing developers to keep the API implementation optimized to the current use cases, allowing consumers to smoothly use the API for their needs, and allowing consumers and collaborators to give feedback as their needs change.

Bonus: The living design gets updated automatically as the implementation updates, using real app behavior as the source of truth.

By making all software development API development, you unlock an immense amount of productivity — but only if it is as easy to share API designs as it is to share code and documents.

It is incredible how much faster software organizations can move when they empower developers to build APIs in a decentralized way. Fast, decentralized development does not require sacrificing organization or coordination. The key is productive collaboration.

Jean Yang is head of product at Postman.

—

New Tech Forum provides a venue for technology leaders—including vendors and other outside contributors—to explore and discuss emerging enterprise technology in unprecedented depth and breadth. The selection is subjective, based on our pick of the technologies we believe to be important and of greatest interest to InfoWorld readers. InfoWorld does not accept marketing collateral for publication and reserves the right to edit all contributed content. Send all inquiries to doug_dineley@foundryco.com.