The API wars are upon us

The APIs that AI agents can find, that agents are successful with… those will be the APIs that win in the market.

Motivation

Your company makes money by charging a fee for calling your APIs, right?

So you want people to use your APIs, yes?

Agentic solution builders will use whichever APIs they can get working most easily:

• API reference information is easy to find
• Reference details are easy to extract in a useful format for including as context in a prompt to a large language model (LLM)
• AI agents using the APIs can successfully perform tasks

The old days

When it was only human developers reading your API reference, you could get away with hard-to-find, obscure reference information that had gaps and errors. And, frankly, you could get away with inconsistent API behavior, unintuitive error handling, obscure error messages, and long-standing bugs.

You could get away with it because your users would form communities where they shared tips and tricks for working around those known issues. Users who had the time and tenacity to persist were called subject matter experts. They liked being in an exclusive, expert user club. And they could charge a high fee to produce software that uses your mysterious APIs.

Irish monk producing a manuscript. A rare, highly valued skill in the fifth century. (source)

The new reality

Now, nobody wants to be an expert at your APIs. Today’s software developers want to focus on building solutions that solve problems. They want LLMs to handle the low-level API calls so they can focus on architecture, security, governance, and user experience.

If AI agent builders can’t use your APIs successfully, they’ll use your competitors’ APIs instead.

Strategy

To make sure all those AI agent builders use your APIs, focus on three things:

1. Streamline your “discover” and “try” user experience
2. Design your APIs to be easy for AI agents to use
3. Optimize your API documentation for use by AI agents

Discover and try user experience

Consider an AI agent that recommends what clothing to wear for the day. For part of that solution, the agent will need a way to know what the weather is like. Is it too hot for a sweater? Is a rain coat or umbrella needed? The human building that agent might search the internet for “APIs for weather”. Then, she might click on the first few results to see if the APIs have the needed functionality. (For example, she might need weather for a specific geographical area with details in specific languages. And she might require response times that meet a minimum requirement.) For those APIs that have the necessary functionality, she’ll then want to try them out.

Shochū no yūdachi (Sudden Shower in the Summer Heat) by Utagawa Kuniyoshi — Japanese woodblock prints in the San Diego Museum of Art (image source)

AI agents will also need to discover your APIs and test them. Consider a self-enhancing AI agent crawling the web, searching for APIs that satisfy given requirements. The agent might scan API reference information to match functional requirements (geography, language support, service level guarantees). Then the agent might scan code samples in the API documentation to evaluate the suitability for requirements. If possible, the agent might even generate test calls and then examine results for completeness and correctness.

To win the API wars, your discover and try experience — for humans and for AI agents — needs to be better than your competitors’:

• Internet search — Make sure information about your APIs is optimized for internet search, test to confirm that your API documentation ranks well with multiple search engines for relevant searches.
• Site search — Make sure that once someone lands on your website, there is a handy, effective site search for more precise searching.
• Live testing — Enable calling API endpoints right from the documentation. Don’t make potential customers have to cobble together cURL or build test apps just to kick the tires on your APIs.
• Test with real data — Create publicly available sample artifacts so people can easily test with real input and get real results. (For example, for cloud storage APIs, create a container that can be listed and searched, where people can add and delete artifacts.) This requires some careful planning and architecture to prevent abuse. But the effort is worthwhile, because people can try out more complex APIs without having to first sign up for the service and set up test environments themselves.
• Authentication — Simplify authentication for trial purposes. (For example, provide a button in the documentation for each endpoint that can be manually clicked to get an API token that can be used only once and for only that endpoint, with only the sample artifacts, and that times out quickly.) This also requires careful planning and architecture to prevent abuse. If the process for obtaining an API token is confusing or time-consuming, users who are already committed to using your API will find stepping through the process to be time worth spending. But users who just want to try things out might give up and go use an API that they can access with less effort.

Designing APIs for AI agents

Human developers can work around inconsistent behavior. Humans can apply lessons learned from previous projects. Humans can ignore irrelevant functionality.

But LLMs are pattern followers. Instructing an LLM to follow a pattern and then expecting it to handle exceptions to the pattern usually ends in tears. It’s like telling a human: “do not think of a pink elephant.”

Ironic process theory: When you hear “Do not think of a pink elephant” you can’t help but think of a pink elephant. (image source)

Your APIs must be designed as carefully as you would design your graphical user interfaces (GUIs):

• Reduce duplication — Avoid having multiple ways to do the same thing so the AI agent doesn’t have to choose.
• Baby steps — On the one hand, breaking tasks down to their smallest steps makes it easier to provide elegantly simple APIs.
• Common tasks — On the other hand, if you can see users performing the same multi-step tasks over and over, judiciously build APIs that perform those common tasks in fewer steps.
• Consistency — Human readers can work out that the parameter named userInput for endpoint A is the same thing as user_input in endpoint B, and the same as input for endpoint C. Although it’s possible an AI agent will handle the inconsistency correctly, why take the chance?
• Simplify authorization/permissions scopes — There will be times when it makes sense for some API users to have the ability to read information but not update it. But permission scopes can become unwieldy. *cough* Slack APIs *cough*
• Error handling — Some API developers consider errors to be edge cases, focus their effort on the successful path, and then use exception handling to catch any and all problems with Hail Mary error messages that say “An error occurred.” That approach is problematic for traditional software applications. But with AI agents, the situation is even worse. At least with software applications, you can build error handling and control the end user experience. But AI agents are generating API calls at run time, so the error handling is dynamic. Add to that the fact that an end user (the person for whom the AI agent is acting) is totally removed from the underlying tools. Those end users will have no way to untangle an error condition if the agent itself cannot roll back half-completed actions or otherwise recover on its own.

One more thing: Monitor your API use and make iterative improvements.

It’s common to make iterative improvements to GUIs that are already in production. For example, let’s say you notice users struggle to find a button. If you adjust the button’s position, color, or size in the GUI, users will adapt easily.

“Wait!” you say. “You can’t iteratively improve APIs!” Let’s say you notice users are confused about the parameters of a particular API endpoint. Changing the parameters of that endpoint risks breaking any applications already using that endpoint with the old parameters. Obviously backwards compatibility is table stakes.

But remember: Unlike hard-coded applications, AI agents generate API calls at run time, based on information like API documentation. That means AI agents can adapt to API changes, as long as you keep the related API documentation up to date. Speaking of API documentation…

Optimizing API documentation for AI agents

Fundamentally, agentic solutions cannot generate their API calls without API reference information. So you have to get this part right.

A human developer reading your API documentation can guess at missing details, ignore obvious mistakes, and handle inconsistent terminology. But an AI agent really can’t. The agent must rely on using your syntax diagrams, parameter descriptions, and code samples to prompt an LLM to generate the required call.

Obviously, the information needs to be clear and accurate. But you need more than that:

• Document tasks, not just single API calls — Imagine an end user wants their AI agent to “Add users in Project A to Project B.” At a minimum, the agent will have to list the users in Project A so it can then add those users to Project B. A human would have no trouble planning that out, but an AI agent might not be able to. Make a list of common tasks and document the steps of those tasks.
• Document choices, reasons — Imagine an optional parameter, with a description that includes: “specifying this parameter causes memory to be released immediately.” A human can figure out if that’s a useful thing to do in a given application. But an AI agent needs more information about what effect or implications releasing memory has, why it’s a good thing, and when (circumstances) you’d want it and when you’d want to avoid it.
• Concrete examples — API documentation often includes simple code snippets in a few programming languages for each endpoint. A human developer would look up the code needed for each step of their task and then pull all the code pieces together, figuring out how to wrangle the output of one piece as input to the subsequent piece. But for anything beyond simple tasks, AI agents can struggle with this. So set AI agents up for success by creating a collection of stand-alone samples that each performs a complete task and includes loading libraries, authenticating, creating needed objects, and using multiple endpoints together.
• Error messages — A human can learn common error cases from experience, a human can search support websites and user communities for help troubleshooting a problem, and a human can try different approaches to resolve a problem. It’s time-consuming and annoying, but humans can struggle through. Troubleshooting a problem, hypothesizing what the cause of the problem might be, analyzing logs to find evidence, and experimenting to see what solves the problem, these are difficult for an AI agent to do. So this is an opportunity to differentiate your APIs from your competitors’: If AI agent builders discover that their agents can recover from errors by following instructions in your well-written error messages, they will use your APIs!

Some people argue that LLMs can truly reason. Others say LLMs are only following patterns. But it doesn’t matter to you who’s right. Your goal is to make AI agents more successful with your APIs than with the APIs of your competitors. Following these recommendations sets AI agents up for success regardless of the reasoning ability of LLMs.

Mettoy Minor toy typewriter instructions (image source)

An extra note about publishing

At this point, many AI agents are scraping webpages and then processing the HTML to extract the needed information from the webpage. Most publishing platforms build incredibly complex HTML files that contain tonnes of HTML elements unrelated to the reference information the AI agents are looking for. (Open your favourite API documentation in a browser, then right-click and select “view page source” to see just how much is there.)

Make the lives of AI agent builders easier by providing a search API and a content API:

• Search API — A site search API that includes not only text similarity and semantic matching, but also uses meta data and leverages tools like knowledge graphs will help AI agents be more successful than relying on only internet search engines.
• Content API — Consider providing an API that returns reference information in plain text or a structured format, such as XML or JSON. Accessing the information this way saves your AI agent builders the time and effort of scraping HTML, and it avoids errors that result from a loss of key information in the processing of that HTML.

For more details and example code, see these related posts:

Make sure AI agents can get at your API reference information

How publishers need to adapt in the era of RAG

Conclusion

Agentic solution builders — and the AI agents themselves — have to discover that your APIs exist, and they have to be able to try them out with as little friction as possible. Your APIs must be elegantly simple and consistent, with intuitive error handling and effective error messages. And your API documentation must be complete, accurate, and accessible in a format that AI agents can use without having to perform elaborate processing. If AI agent builders find your APIs the easiest to use and most successful for their solutions, you’ll be victorious in the API wars!

Coming to a galaxy near your