Aug 10, 2022
·
7
Min Read

What “APIs Instead of Meetings” Looks Like for 99% Developers

by
Jean Yang
Share This Article

Recently, Coinbase CEO Brian Armstrong published a blog post about how they operate efficiently at scale. One of the main points: “APIs instead of meetings.” Especially in large companies, Brian writes, product and engineering teams can reduce their meetings if they document their team’s API.

From Brian Armstrong's blog post, "Operating efficiently at scale."

I completely agree with Brian. With an up-to-date picture of your systems, everyone runs faster. But what about all the teams who don’t have the luxury of maintaining an up-to-date API catalog?

In this post, I’ll talk about why there often needs to be so many meetings, why API catalogs remain out-of-reach for most software teams, and how API maps help reduce meetings for “99% developer” teams.

Why meetings are often the only solution

Unless there is a well-established culture of documentation and communication, it quickly becomes unwieldy to navigate code bases. It becomes hard to answer any of these questions:

  • Does there exist functionality to do the thing I want to do?
  • Does that service really provide the functionality I want?
  • How do I get the functionality I want from this service?

The result is that there is duplication of work, more opportunity to incorrectly use functionality, and more opportunity to expose buggy functionality to the end user.

Brian Armstrong talks about this as a problem at scale, but these issues can emerge on much smaller teams. In my hundreds of developer conversations, people have cited these issues not only across different services, but also across different endpoints of the same service. Deadline pressure is a major culprit. Things get worse when teams accumulate code not written by those currently on the team, either due to team churn or due to working with contractors. Legacy subsystems make these problems exponentially harder. And, if your team experiences churn or  works with external contractors, systems become “legacy” the moment code gets handed over.

Why API catalogs remain elusive for “99% teams”

According to this blog post, Coinbase solved their problems by adopting an API catalog. With the API catalog, there’s a central registry of services with their API endpoints, where engineers can look to figure out if an API already exists, along with more details about the API. The main way API catalogs reduce meetings is by providing a central source of truth tied to the functionality of the code.

API catalogs are great—when they’re well-maintained. But state-of-the-art API catalogs require teams to do nontrivial work to add their API to the API catalog, through either uploading an API spec or manually annotating their API. This means either everyone on a team needs to stay disciplined, or there needs to be a group of people who clean up after everybody else.

There a few main reasons API documentation is hard to maintain:

  • Documentation doesn’t match reality. Most of the teams we talk to report substantial drift between API specs and actual code behavior. Unless every developer who is updating an endpoint or fixing a bug is diligent about updating annotations and/or documentation, the catalog quickly goes out-of-date—and meetings become necessary.
  • Documentation is not a priority. Most of the organizations we’ve encountered have told us that only a small amount of their endpoints are documented. There are many reasons: deadlines loom; the API endpoint starts out as experimental. As a result, the catalog is only a partial reference.
  • The original authors aren’t around to provide documentation. Whether it’s because a company has been around for a while, or because an organization has experienced churn, or because a team works with third-party contractors, there are many teams where the people who originally wrote the API functionality are no longer with the company. It’s challenging to provide meaningful documentation when the original author is gone, often along with most knowledge about original intent and edge cases.

If a team has the resources to dedicate real time to keeping API documentation up to date, then it’s possible to avoid meetings.

Having the resources to maintain an API catalog is a huge “if,” especially for the “99% developer” teams that we work with. These are developers outside of Silicon Valley, often at companies that are not tech-first and on under-resourced teams. These developers aren’t on teams with time to spare to maintain an API catalog. So they continue having meetings—often meetings where figuring out what to ask each other is not straightforward.

How API maps help you with those meetings

If we agree that APIs reduce meetings, then the question becomes how to make API catalog functionality accessible to teams who don’t have time to catalog their APIs. In this section, I’ll talk about how API maps achieve the same goal.

You probably haven’t heard of API maps before. We came up with the term to differentiate from “API specs,” as people often associate specs with artifacts that are human-generated, incomplete, and not generally intended for human consumption. The API maps that Akita builds, on the other hand, are automatically generated, capture any traffic observed, and are built for people to understand the system they’re working with. Simply drop the Akita agent wherever you’re running API traffic and give it permission to listen.

We at Akita got into the business of building API maps because we originally needed API specs for the same reason you might want an API catalog: we needed a central source of truth about API endpoints, in order to build the software analysis solution we originally set out to build. We were surprised—and ultimately decided to pivot to focus on API maps—when our users asked for more functionality for understanding the API specs we were generating.

The first “killer feature” of API maps ended up being automatically generated path parameters:

Akita API map with automatically inferred API path parameters.

When a developer writes an API spec by hand, path parameters are also something they write by hand, based on their knowledge of an API. Using other API and observability tools, developers need to manually combine API paths like `…/services/service0/learn/…` and `…/services/service1/learn/…`, or at least provide explicitly mapping rules. The Akita agent passively watches API traffic and uses algorithms to automatically infer path parameters, making it possible to get parameterized API specs within minutes of setting up the Akita agent.

Early Akita API map users struggled with browsing large numbers of endpoints, leading us to make two crucial additions to API maps: usage information and structured exploration. Because the Akita agent passively watches API traffic, it has easy access to the necessary information. Below we show how to sort API maps by usage and latency, as well as how to filter APIs based on endpoint structure and data types.

Akita API map entries sorted by decreasing usage.
Search and filter for Akita API maps.

We at Akita are able to build on top of API maps for other drop-in API observability functionality. Because of the automatic path parameter inference, we’re also able to provide per-endpoint metrics and errors. For instance, in the graph below you can easily see that single endpoints are causing latency spikes:

Per-endpoint API metrics with Akita.

Here are some use cases that Akita's API maps support, directly and indirectly:

  • Understanding how to call an API they didn’t write, but need to use. For instance, we have frontend teams using Akita API maps to understand how to call backend APIs.
  • Moving fast while working with a legacy API they didn’t write. We have users who got handed a pile of code that they now need to maintain, who still want to move fast building features. API maps have helped these users understand the code that existed, 
  • Drop-in observability. We have users who use our drop-in per-endpoint metrics and errors to quickly get an idea of which endpoints to pay attention to. Automatic per-endpoint observability makes it easy to monitor the part of your system you know you care about, while quickly narrowing down potential issues to small sets of API endpoints.

For these use cases, automatically generated API maps make it possible for developers to have fewer meetings and fewer opportunities to become bottlenecked on other team members. This is especially helpful in situations where those meetings were never possible in the first place, as is the case for legacy subsystems. 

Reduce your meetings today

At Akita, we agree that APIs are the source of truth when collaborating across your organization. This is why we’ve been working hard on not only a solution that drops in and listens to your APIs without much work on your part, but that analyzes and presents the traffic information in a way that makes it easy for you to collaborate, with active teams or with the phantom developers of legacy subsystems. We see ourselves as part of a new ecosystem of tools that will make it easier for you to parachute into any system and understand what’s going on.

We’re in private beta. We’d love for you to try us out and tell us what you think!

Photo by Flipsnack on Unsplash.

Share This Article

Join Our Private Beta now!

Thank you!

Your submission has been sent.
Oops! Something went wrong while submitting the form.