What Makes a Quality API Contract?

After a recent post I made on LinkedIn, where I discussed why high-quality API contracts are essential for agentic use cases, I received a question about what exactly defines a “high-quality API contract“. This article is aimed at answering that question.

Before defining what makes an API contract high-quality, it is worth revisiting what “quality” itself means. I have been strongly influenced by the ideas of Dr. W. Edwards Deming, often called the “Father of quality”. He described quality as “meeting or exceeding customer expectations” and emphasised that “only the customer can define quality.“ Beyond this, quality practitioners often describe it as fitness for purpose, and conformance to specification.

How do these ideas of quality apply to API contracts - specifically OpenAPI descriptions and Arazzo description files? To clarify, there are many aspects of API quality in general, but in this post I am focusing primarily on API design quality (how well the API follows sound design principles) and API description quality (how clearly API behaviour is documented for humans and machines). The definition of quality yields four implications for OpenAPI and Arazzo description files:

1. We cannot talk about quality without talking about standards. We cannot improve quality if the customer/user expectations are not clear. API teams define what API design-quality is by defining the quality standard in explicit detail in an API design style guide. The style guide sets the quality bar for API contract quality, but it also means that organisations that don’t have an API style guide do not have the table stakes for the game. Implication: If customers are not happy with the design of an API, the API style guide (that is, the quality standard) should be updated to match API consumer expectation before fixing the API design itself.
   I wouldn’t go into the practical details of what an OpenAPI or Arazzo file should contain – many excellent open-source style guides already do that, such as those from Zalando, Belgif style guide, and AEP.dev

2. We cannot talk about quality without identifying the customer and the job they are trying to fulfil. We must be clear on who the customer/user of the API contract is. We have to also be clear on the customer needs, or Jobs-to-be-Done (JTBD). The customer of an API is an API consumer, and I consider the main categories of consumers of OpenAPI and Arazzo contracts as:

   1. Developers. Their JTBD for APIs usually involves building some kind of integration.

   2. Deterministic software tools. For example, developer portals that render the API contract, SDK generators, GitOps/APIOps tools that deploy APIs with the API contract, testing tools that use the API contract to run tests, and so on.

   3. AI tools: LLMs and AI agents are consumers of API contracts too. I put them in a different category here because they are non-deterministic and have their own requirements for API contracts if they are to use them properly. For example, they need:

      1. High-level API operations and workflows that match their JTBD, rather than a large number of low level API operations that may be confusing for them. Giving agents too many tools and too much context can make them perform worse.

      2. Good examples in the contracts

      3. Explicit hints in error messages on what to do if those error messages are encountered

      4. An API design that minimises token usage

3. The API style guide should be a living document that defines and maintains API contract quality standards. The API style guide should evolve continuously based on consumer feedback. It is, and should be, defined through a co-creation process with API consumers. As a living document, its rules should be updated based on standardised API consumer requirements. For example, many API style guides will need updates to reflect the specific needs of AI tools.

4. An API contract linter is really an API contract quality verification tool. In a recent LinkedIn post, Dave Shanely mentioned that the excellent API linting tool, Vacuum, is an “OpenAPI quality analysis tool“. I like this description because it elevates API linting to a broader quality conversation, viewing it as a quality-check rather than just linting. An API linter is in effect, an executable verification of the quality standards defined in the API style guide.

In summary, a quality API contract is one that fully complies with its design standards. But beyond compliance, those standards should be co-created and continually refined with all categories of API consumers in mind - developers, deterministic software tools and AI systems.