Understanding Prod Faster and Better with Our New API Model Page

by

Jean Yang

At Akita, our goal is to help every developer understand what their production system is doing, regardless of whether they’re experts in monitoring and observability—and whether they wrote the system or not. But it’s hard to tell developers about parts of their system they don’t yet understand!

In this blog post, we introduce our new and improved API model page, the latest milestone in our journey to help developers like you understand the behavior of your production systems. We’re proud of our progress since the last iteration. And we would love your feedback.

So you’ve become responsible for a service you didn’t write

A Tweet about what is happening at Twitter right now.

Say your company just got taken over by new leadership. Now there’s massive churn on your team. You’re responsible, maybe even on call, for services you didn’t write, where the original team is nowhere to be found.

You’re supposed to keep this system alive—while demonstrating your ability to contribute to the team by shipping new features at a steady clip on top of it. You have access to the source code, but this doesn’t answer the questions you really want to know, including:

What endpoints are still in use? If you take out endpoint A, what falls down?
If you add your planned functionality to endpoint A, does that impact performance for endpoints B and C?
Something is slow. Which one of endpoints A through Z is it?
Something is throwing errors. Which endpoints A through Z is doing so?

While many of us have been watching an infamous version of this story unfolding before our very Twitter timelines, the situation I describe here is not too far off from reality for many software developers. The rise of SaaS and APIs means that it’s harder than ever to understand production behavior. Right now, there’s also more turnover on software teams than ever before.

As a result, more and more developers are responsible for maintaining and building on top of software services that they didn’t write—and where the original creators may be nowhere to be found. At the same time, companies are putting more pressure on developers to be productive than ever before. What this means is that it’s become incredibly important to build tools that help developers understand and explore the behavior of their own production systems, without a lot of setup or maintenance, in order to help developers ship and build more productively.

Why it's hard to explain unknown software behavior to developers

A few years ago, we at Akita started working on the problem of helping developers move faster with complex systems they don’t fully understand.

At first, the problem we thought we were solving was this: developers telling us they didn’t even know what endpoints they had, or what data those endpoints were dealing in.

Easy, we thought. We’ll just watch the API traffic and tell developers what we see.

Except not so easy! First, we showed users all of the traffic, with some light cleanup from grouping API endpoints together, in the form of an OpenAPI specification. While there were a couple of users who would sit and read the whole spec, most users told us they wanted something easier to explain. It turns out there’s a reason users don’t use Wireshark for monitoring and visibility. These users’ logs may not be comprehensive enough to help them understand their system, but at least they know what they mean.

This was a turning point for us: we went from thinking of what we were building as documentation to a live, explorable representation of system behavior. Our goal shifted from showing users everything that was going on with their system, to giving them a way to answer the questions they cared about using data about everything going on with their system.

Check out a few "vintage" versions of the Akita API model page here and here.

Meet our new API model page

In the last couple of months, we’ve been working on a series of improvements to help our users more quickly understand what they want to know:

How much API traffic have we seen overall?
What are the busiest, quietest, fastest, and slowest endpoints?
What information does Akita infer about the endpoints—and how to explore it?
Is the API what we expect in size, shape, and performance?

We now put this information up front and center:

Here are a few things we cleaned up, shown in Dark Mode:

Previously, the first thing you saw on the page was a graph that took a long time to load. We found the users wanted to know one piece of information from the graph: how much traffic went into building this API model. We’ve replaced this graph with quick stats at the top of the page and now focus the page around API model exploration.

Previously, the filters were hidden and users often had a hard time discovering information about their API they didn’t already know to look for. We now make it much more clear how you can now explore your API models.

New endpoint filters are up front and center.

Previously, Akita was inferring lots of information about endpoints, but users needed to dig into this information themselves. The new Endpoint Details view now provides a friendlier view of this information, from path parameters to the shape of response payloads. It’s now organized more similarly to other tools you might be used to, like the Chrome DevTools.

See your endpoint details with our new Endpoint Details view.

Bonus: better endpoint search! We now support fuzzy search and being able to select multiple search terms at once.

Check out our docs here and here.

We’d love your feedback

Whether you’re weathering new management, team churn, or just trying to figure out your way through an annoying bug, we’d love to have you try Akita. As you can see, we take feedback and feature requests from our beta users seriously, so join our beta today to help us build the drop-in API monitoring and visibility tool you wish you had.