The Taxonomy of API Operations
A behavioral classification system for machine-to-machine APIs.
API documentation is always incomplete. But that doesn't matter if those who consume it are developers. Like any other human being, developers have the power of intuition. And that makes all the difference. Unlike an AI agent, a developer can go through a long list of API operations and intuitively group them by intent. Or infer the format for an undocumented data type based on information available elsewhere. Or even understand that an operation is legacy just by looking at its name. When AI agents see every API operation as identical in nature, they face an enormous cognitive load. They become disoriented when operations take too long to complete or in the face of a potential risk. In other words, they spend more tokens and require more help from humans. What is the solution, then? Keep reading.
This article is brought to you with the help of our supporter, Scalar.
Scalar is the modern OpenAPI platform for the entire API lifecycle. Govern APIs with Scalar Registry, test offline with their built-in Client, generate beautiful documentation, and ship SDKs instantly - all from your single source of truth.
So, what exactly is the problem AI agents have with the API documentation you and I have been creating? Actually, there’s more than one kind of problem. And they all have to do with the ability to understand what each operation really does. Because of that, agents have to scan the whole API documentation every time just to get the right combination of operations. Let’s look at the most important challenges AI Agents face today while doing operation discovery:
Unknown side effects: there’s no way for an AI agent to know if an API operation produces side effects just by looking at its name. How would you know, for example, if
POST /orderssimply creates an order entry or triggers a chain of events that eventually end up in shipping some product to a customer?Runtime uncertainty: an AI agent can’t understand if an API operation can perform a search or if it simply returns a static list. Take, for instance, the
GET /productsoperation. Does it always return the same list of products, which you can filter after the fact, or does it perform a dynamic search on a live product catalog?Orchestration fragility: if an API doesn’t explicitly declare its high-level orchestration paths, an AI agent is forced to build its own step-by-step plans. Operations such as
POST /userscan be a part of a bigger workflow, which involves creating and billing a new customer.Connection timeout: AI agents treat all API operations in the same way. If an operation is taking too long, an AI agent assumes there’s a timeout. However, it’s normal for some operations to take a long time to finish.
POST /reports/generate, for example, looks like it will take some time to complete. However, to an AI agent, it might seem like any other operation.Constraint blindness: it’s very hard for an AI agent to infer awareness of its own identity, privileges, and constraints. Without that information, AI agents will attempt to use API operations until they receive errors, which leads to wasted resources. How would an AI agent know that an operation like
GET /mecould be useful to understand its own identity and privileges?Inefficient polling: there’s no way for an AI agent to remain idle waiting for an event to finish. It will try to periodically get information about the event. Suppose the agent executes an operation to perform a bank transfer. The next logical step would be to periodically call
GET /transfer/{transferId}to understand if the transfer with the corresponding ID is finished.Loop saturation: AI agents that have to process a large volume of data will simply loop over individual operations until their task is finished. This situation usually leads to reaching API rate limits or, even worse, to being flagged by a gateway as a DoS attack.
Blind execution exposure: AI agents don’t know how to separate safe experimentation from critical production mutations. A human would try an operation like
POST /chargesagainst a mock before going to production. However, an AI agent doesn’t have that intuition.
Many of these problems aren’t exclusive to AI agents. If developers interacting with an API don’t have enough knowledge about it, they’ll also face similar challenges. Having good documentation helps, but many times it’s not enough. So, what else can you do about it? One solution is to stop thinking of API documentation simply as a way to expose resource and collection names. But that’s too dramatic, and we don’t want to kill what already exists. Instead, what I propose is to augment the existing API naming conventions with an operation taxonomy focused on behavior. The idea is to group operations into categories based on how they function and the impact they have. This distinction allows AI agents to understand not just the resources that operations interact with, but also their scope, safety, and eventual cost. How would such a taxonomy work, then?
The taxonomy of API operations groups them into eight categories based on their behavior and system impact. By classifying operations as atomic, workflow, asynchronous, introspective, discovery, reactive, bulk, or simulated, you create a predictable map that helps machines navigate APIs safely. Here are the eight categories, in more detail:
Atomic operations: granular, single-purpose resource manipulations, e.g.,
GET /customers/:id,POST /products. They offer precise control but high reasoning overhead when you need more than one atomic operation to complete a task.Workflow operations: high-level, intent-based operations that encapsulate multiple steps into one single request, e.g., Stripe’s
POST /v1/checkout/sessions, HubSpot’sPOST /v1/crm/pipelines/merge.Asynchronous operations: long-running background jobs that break the immediate request-response cycle, returning a
202 Acceptedresponse and a status operation for polling.Introspective operations: meta-calls that give consumers information about themselves or the context they’re interacting with the API, e.g., rate limits, identity, credits, and security token scopes.
Discovery operations: dynamic ways for consumers to explore available capabilities or product catalogs at runtime, e.g.,
GET /products,GET /operations.Reactive operations: event-driven mechanisms like Webhooks or Server-Sent Events, where the API pushes data to the agent automatically.
Bulk operations: mass processing operations designed to handle arrays of items in one request to prevent rate-limit exhaustion.
Simulated operations: dry-run capabilities that validate logic without mutating production data, e.g., using a
dry_runparameter,POST /invoices/preview.
One thing I want to clarify is that operations can be on more than one category. Similarly, there are operations that you’ll have a hard time categorizing. That happened to me with operations that mostly didn’t make sense in a RESTful way. Things like DELETE /products. Does it delete all the products? Or, what does it do? Finding one of these operations certainly gives you the opportunity to redesign your API. I’d iterate on that until finding a good alignment between the behavior I want the API to convey and the potential needs of consumers.
As you can see, sometimes there are difficulties in following this classification system. While the first challenge is finding the right category, there are other issues to consider. One is related to how you store the category information inside an OpenAPI document. I suggest using something like an array attribute named x-taxonomy, which you can put inside an operation and add multiple categories to. This will make the taxonomy machine-readable, which is our goal anyway. Another challenge has to do with the inevitable category drift. As an API evolves, what was first considered an atomic operation might become a workflow. Or something else. Overall, you’re introducing a new layer of information that you’ll have to keep in sync with any future API changes.
Feeling unresolved? That’s because the decision to adopt this taxonomy depends on your primary consumer. As far as I see it, you have two options. If your API is purely for traditional developer-built integrations or direct human consumption, the effort to add a taxonomy might be higher than its benefit. However, if you’re targeting AI agents, a taxonomy is something you need to have. Without it, machine consumers won’t be able to make the most of your API in a cost-effective way. And they’ll probably look elsewhere, which is something you want to avoid, right? Well, I’ve made my point. The decision is in your hands now.