API Documentation for Machines
What are the elements that make API documentation easily consumable by a machine?
API documentation is a topic thoroughly explored. I've been writing about all the different elements of good API documentation and what you, as an API producer, should pay attention to. The relationship between good API documentation and developer experience is undeniable. Documentation, if done well, reduces the friction consumers have when interacting with an API for the first time. But, what about machines? Yes, machines. Read on to see what I'm talking about.
This article is brought to you with the help of our supporter, Scalar.
Scalar is a suite of powerful & customizable developer tools to help you at all stages of API development. Create beautiful API Documentation in a notion-like editing experience.
See, we now have another type of API consumer. One who doesn't have the same predicaments as you and I. One who's much faster than any human. One who can do a million things at the same time. It's a machine but one with the agency to decide what to do and how to get things done. Not one that's been configured and programmed by a person. I'm referring to AI agents, of course. The recent evolution of AI has led us to a point where it's possible to have agents acting on our behalf.
AI agents don't necessarily care about the same things we do when they access the documentation of an API. Even though they can read—and interpret—documentation that was meant for human consumption, they don't pay attention to the same things we do. For example, why would a machine care about how easy it is to consume an API tutorial? Or, how important is it for an AI agent that you provide personalized examples? Machines need a different type of fuel to operate well.
To begin with, everything you document has to be in a format that's as structured and machine-readable as possible. The key here is to disambiguate as much as you can, even if you have to repeat yourself. So, don't bother with the formatting of your documentation or the look and feel of your API portal. Instead, focus on using well-known API definition standards based on machine-readable formats. Use OpenAPI for documenting REST APIs, AsyncAPI for asynchronous APIs, Protocol Buffers for gRPC, and the GraphQL Schema Definition Language. Whenever possible, store the API definitions in several formats, such as JSON and YAML, for easy interpretation by AI agents.
But that's not enough. If you don't have all your operations clearly defined, AI agents will have a hard time understanding what they can do. Make sure you clearly define all operation parameters. Specify what the input types are so there are no misunderstandings. So, instead of saying that everything is a "string," identify each individual input format. Do the same thing for all responses, so there's no doubt about its shape. Specify all the constraints that your data has. For example, always include the maximum length of attributes where applicable and identify what fields are required. Additionally, follow the familiarity principle when naming parameters, objects, and attributes. An easy approach is to follow what the most popular APIs in your area or vertical are using.
What happens when there's an error? AI agents need clear information whenever there's an error when they're consuming an API. In the case of a REST API, it's very important to distinguish between an HTTP 401 and a 403 code. One thing is a failed authentication. Trying to access a forbidden resource or operation is something totally different. Don't try to reinvent the wheel. You can, for instance, follow the Problem Details for HTTP APIs (RFC 9457), and you'll have a good base for defining all the facets of possible errors. Something else to consider is adding examples to all error definitions. AI agents using LLM technology work well by interpreting existing information. In this case, an example can convey what an error would look like in a real situation.
Many times, AI agents use one of your API operations in an isolated way. However, many other times, your API and its operations are just one single step of a larger workflow. What really helps is documenting the possible use cases you anticipate can be interesting in a machine-readable way. The format you use for describing the workflows should let you identify all the steps required to completion as well as the dependencies between those steps. A very good candidate specification for documenting workflows is Arazzo from OpenAPI.
If you have all these items in place, you're in a good position to offer AI agents the best way to interact with your API. There are other things that can make things even better, like defining the authenticating methods you support. Or offering extensive examples for all operations in a machine-readable format. Your goal is to make it very simple for a piece of software to find your API, analyze the documentation you provide, understand what the operations are, find if there's a way to fulfill the use case it has and execute it. You want to streamline everything and make it really simple to discover and execute.
I appreciate how you emphasize the importance of streamlined workflows! EchoAPI makes managing API documentation so straightforward, allowing me to focus more on coding rather than paperwork.