What is API Quality?
How do you know if you have a high-quality API?
Everyone agrees that having a high-quality API is critical. However, most people who run APIs don’t know how to measure quality. To them, “quality” is something subjective. So, they can say if an API has good quality but they aren’t able to quantify it. To me, quality is the “glue” between all the stakeholders of an API. If you’re a consumer you naturally care about the quality of an API. If you’re the API producer, you want it to have the best possible quality. If you’re a developer, you’re interested in building something that is high quality. If you’re a business decision-maker, you want the API quality to represent your products and your company. So, if API quality is something everyone is interested in, what is it exactly? Follow me as I explore its meaning.
This article is brought to you with the help of our supporter: Speakeasy
Further expanding its best-in-class API tooling, Speakeasy now empowers teams with open standards. The platform simplifies OpenAPI Overlay adoption so you can focus on building. Click the button below to check out the playground.
My quest to find what API quality is began in October 2024. Back then, I asked on different social media platforms, “What is API Quality?” My hope was to find someone who could, without a doubt, share a definition. That didn’t happen. What happened, instead, was a diverse torrent of possible definitions. To some people, API quality is a measure of how an API adheres to a maturity model. To others, quality is related to the usability of the API or its consistency. There are other people who defend quality means semantic clarity. And the list goes on and on. I wasn’t happy, obviously. So I tried something else.
In November 2024, I rephrased my question and used examples of other industries to make my point. I asked, “How do you know what the quality of a restaurant is?” Then, I asked people to transpose those elements to the quality of an API. Now, I could see answers different than the ones I had seen before. Answers that were more aligned with the needs of consumers. Some people mentioned that quality means an API satisfies all the requirements. Other people added that a high-quality API solves business needs. Others mentioned good documentation, flexibility to future needs, compliance with relevant industry standards, and also — why not? — good performance. “Now we’re getting somewhere,” I thought.
As I continued my quest, I categorized all the elements that make API quality into three dimensions. I followed the great work of Seth Godin on the same topic. To Godin, the definition of quality isn’t easy to synthesize. So, he proposes “three kinds of quality.” In his book “The Practice,” he calls the first kind of quality “technical” and associates it with a product meeting specifications. The second kind, luxury, is what most people actually understand as quality. Luxury is what sets a product apart. And finally, he calls the third kind of quality “creative magic.” This is the kind of quality that makes consumers recommend a product. I feel this representation of quality is something I can translate into dimensions of API quality. So, I started to craft my “API Quality Framework.”
First, you have the technical dimension, where all the quality metrics identify how well the API works. I’m talking about metrics like performance, alignment with requirements, and security. Then, you have the luxury dimension, with metrics that identify how the API fits into consumers’ use cases. Some metrics here include things like usability, business needs, and functionality. Finally, there’s the creative magic dimension. Now, the metrics all relate to the potential of the API, with what it allows you to do. Examples of metrics are flexibility, creativity, and scalability. In short, technical quality means “it works,” luxury means “I can use it,” and creative magic means “I love it.”
Reflecting on these three API quality dimensions made me realize that some of the metrics were easily led by the producer, while others were purely led by the consumer. A metric like “requirements,” for instance, is something a producer has total control of. I mean, given a list of requirements, a producer can lead the work in such a way that makes the API score 100%. On the other hand, a metric such as “creativity” can’t be controlled by an API producer. Only a consumer can define whether an API provides creativity or not. In the middle, you have the luxury metrics, which both producers and consumers can lead. This segregation relative to who can control what metrics made me see API quality as a spectrum. You start with the technical quality on the left-hand side, which is producer-led, move through luxury quality, and end on the right-hand side with creative magic, which is consumer-led.
What’s interesting and becomes evident after this exercise is the amount of API quality a producer can control is quite limited. Most of the perception of quality is led by consumers. They’re the ones who identify if an API is high-quality. So, in the end, most of the metrics that you need to measure are controlled by consumers. That’s why, for instance, time-to-first-call (TTFC) is so important but, at the same time, depends heavily on what consumers do. In the end, an API exists to serve its consumers, not the other way around.
This post was originally published on the API Changelog newsletter as “What is API Quality?”
