Quality is the ultimate purpose of API governance — the whole apparatus of rules, engines, policies, and people exists to produce APIs that are correct, consistent, complete, and genuinely good to use. But quality is also one of the slipperiest concepts in the API space, because it’s easy to assert and hard to measure. What makes an API high quality? Consistency, certainly — APIs that follow the same patterns so developers can move between them. Completeness — definitions that fully and accurately describe what the API does. Correctness — APIs that actually behave the way their contracts say. Reliability, good documentation, security, usability. Quality is the sum of all these, and governance is the discipline of producing it systematically rather than hoping for it. I’ve spent years trying to make API quality measurable and governable, because quality that can’t be measured can’t be reliably produced, and quality that depends on individual virtue rather than systematic governance won’t scale.
The measurement problem is where I’ve focused a lot of energy, because you can’t govern quality you can’t measure. I wrote in 2012 about developing more meaningful API metrics, and the recurring challenge is that the easy metrics — number of calls, number of developers — don’t actually measure quality. Real quality metrics have to capture consistency, completeness, reliability, and usability, which are harder to quantify. The quality-of-service endpoint I wrote about in 2016 was one attempt to make quality measurable and visible. The deeper realization is that machine-readable API definitions make quality measurable in a new way: when your API is described in OpenAPI, you can systematically check it for completeness, consistency, and adherence to standards, turning quality from a subjective judgment into a measurable property. Governance engines like Spectral are, fundamentally, quality measurement tools — they assess whether an API definition meets the quality standards encoded in the rules.
The ratings dimension is where I tried to make API quality comparable across providers, and it’s an ambition I’ve pursued for years. I wrote in 2017 about the progression from awareness to observability to API ratings, and developed an API rating formula to assess quality systematically. The grand vision I articulated in 2015 was creating the Standard & Poor’s or Moody’s for the API economy — independent quality ratings that would let consumers assess the quality and trustworthiness of an API the way credit ratings let investors assess bonds. This rating ambition reflects the belief that API quality should be measurable, comparable, and transparent — that consumers should be able to know, before they commit, whether an API meets a quality bar. The apis.io Spectral-powered ratings system I built realized a version of this, applying governance rules to produce quality scores. Ratings are quality made comparable, and comparable quality is what lets the market reward good APIs and penalize bad ones.
Consistency is the dimension of quality that governance is most directly designed to produce, and it’s where the value is most obvious. I wrote a pointed analogy in 2024 about how we let each team of electricians wire things up in their own way without a plan or standards — no wait, we only do this with APIs. The point is that inconsistency is a quality failure that no organization would tolerate in physical infrastructure but routinely tolerates in APIs. When every team builds APIs differently, the result is a low-quality portfolio where nothing is predictable, developers have to relearn conventions constantly, and the whole is far less than the sum of its parts. Consistency — produced through governance standards applied across the organization — is a foundational quality property, because it makes the APIs predictable, learnable, and composable. The spectrum of governance rules I’ve written about is fundamentally about producing consistency, which is to say producing quality at the portfolio level.
The relationship between quality and the developer experience is where quality stops being abstract and becomes concrete. The charismatic APIs I wrote about in 2024 — Stripe, Twilio — are charismatic because they’re high quality in a way developers can feel: consistent, complete, well-documented, reliable, a genuine pleasure to use. Quality isn’t just technical correctness; it’s the whole experience of working with an API, and the highest-quality APIs are the ones that respect and delight the developer at every touchpoint. This connects quality to the human experiences I’ve written about — a quality API produces good experiences (smooth onboarding, reliable operation, clear documentation), and a low-quality API produces frustrating ones. Governance for quality, in this light, is governance in service of the developer experience: the rules and standards exist to produce APIs that are genuinely good to use, not just technically compliant.
Quality, in the end, is the goal governance serves, and good governance is just the systematic pursuit of quality. I wrote in 2024 that good API governance is just guidance — and the guidance exists to produce quality. The danger is mistaking compliance for quality: an API that passes all the linter rules isn’t necessarily a high-quality API, just as an API that’s technically correct isn’t necessarily a pleasure to use. Quality is richer than rule compliance; it includes the things that are hard to encode in rules — good design judgment, genuine usability, thoughtful developer experience. So while governance is the systematic engine for producing quality, quality also requires the human judgment and care that rules can’t fully capture. The deepest point about quality is that it’s the actual purpose of everything else in governance. The rules, the engines, the policies, the people — all of it exists to produce APIs that are correct, consistent, complete, reliable, secure, well-documented, and genuinely good to use. Quality is what governance is for. An organization that produces high-quality APIs has succeeded at governance regardless of how elaborate its apparatus is; an organization that produces low-quality APIs has failed at governance regardless of how many rules it enforces. Keeping quality as the north star — the measurable, governable, but ultimately experiential goal that all the governance machinery serves — is what keeps governance from becoming compliance theater and keeps it focused on the thing that actually matters: producing APIs worth using.
References
- Developing More Meaningful API Metrics
- How Are We Going To Create The Standard And Poor’s And Moody’s For The API Economy
- Quality Of Service API Endpoint For Your API Platform
- From Awareness, Observability, To API Ratings
- The Basics Of My API Rating Formula
- What Makes Charismatic APIs
- We Let Each Team Of Electricians Wire Things Up In Their Own Way Without A Plan Or Standards — No Wait, We Only Do This With APIs
- Good API Governance Is Just Guidance
- The Spectrum Of API Governance Rules
