Getting the "Right" API Standards

Strategic software consulting takes me to some interesting places to have some interesting conversations. While the industries, sizes, and situations differ, you'd be surprised how similar many of the current discussions are. For example, I've been asked on several occasions:

"Sure, stormin' and normin' governance is great, but can we just skip to the end and get the API standards?"

Sadly, asking people what comprises the "definitive API standards list" is kind of like getting people to agree on the best pizza topping; sure, you'll find a person here and there who might agree, but others certainly have differing opinions, and that doesn't mean they're wrong. 

"But, surely after all this time, there's a collection of  'best' standards we could just mandate all groups use, right?"

Sure, and - theoretically - it is possible to measure a coastline. And then you try to do it, and suddenly find yourself drowning in nuance. Let me explain.  

Mapping Coastlines for (No) Fun and (Little) Profit <title>

The coastline paradox is a well-known phenomenon that is initially counterintuitive. It states that the coastline of any landmass lacks a well-defined length. 

"It is the 21st century. We have pizza delivery robots and self-driving cars (kinda). How is that even possible?"

A coastline can be measured. The wrinkle is that, depending on the scale of measurement you use, you'll get different results. Where the land meets the water has features at all scales, from inlets and bays hundreds of miles long to tiny fractions of a millimeter. There is no obvious size of the most minor feature that should be considered when measuring, and, as a result, no single length to a landmass. 

There's some fascinating history on the Wikipedia page if you're interested. However, for our purposes, it is sufficient to remember that with a coastline, the finer the ruler, the longer the coastline. Or, said another way:

If you attempt to capture infinite detail, the result is infinite complexity. 

This GIF, from the Wikipedia explanation, does a fantastic job of illustrating the fractal nature of the problem. 

Greater detail doesn't bring greater order; it reveals more edges.

If I grossly stereotype, the reason so many of us enjoy working with software is that there is an order there, a predictability. Seeing disorder is unsettling, and our first impulse is to standardize all the things; the reflexive thinking is that the more precisely we define a system, the clearer it should become. 

In reality, it's the opposite. Like measuring a coastline, the closer you zoom in, the more irregularities you find. The harder you push to make the pieces fit, the more you realize that your neat little model isn't describing the system; it's revealing your vantage point.

When you start enumerating what "good" APIs look like, you bump into exceptions: "What about async APIs?" "Does that rule apply to internal-only endpoints?" "Do we version events the same way as REST?" "What about keeping our taxonomies consistent?" Each refinement resolves one ambiguity but exposes two more. It's a fractal process, like the CISO turning over a rock of an audit process and discovering all the variant APIs scurrying around; structures repeating endlessly, similar but never identical.

API standards creators who mistake precision for progress soon find themselves maintaining an ever-expanding perimeter of edge cases. Every new rule spawns a new footnote, and the once-elegant principles degrade into a procedural thicket. Worse, as detail increases, adherence decreases: developers stop reading, exemptions multiply, and the document becomes a bureaucratic reef teams seek to avoid. It is a calculated decision, and - in most cases - the comprehension overhead of a ballooning, "complete" document just isn't worth it.

In the coastline paradox, smaller rulers make the boundary longer. In governance, more detail makes compliance harder. Neither gets you closer to a useful truth, only to exhaustion and avoidance. The art isn't in capturing every contour, but knowing the scale of granularity necessary.

The "trick" is hitting upon a standard scale that is useful.

Standards are only productive when they are designed to produce a specific outcome. Marine biologists, shipping companies, and tourism boards all describe the same shoreline differently. That's not because one group is wrong, but because they're generating different outcomes. As such, they operate at different resolutions. The coast only becomes "infinite" when you insist on measuring every grain of sand.

API standardization efforts must narrow the frame: Pick one actual issue that is causing real, recurring pain. Not the abstract desire for "consistency," but the concrete problem behind it: error responses that vary wildly, APIs that can't be versioned safely, or naming conventions that force consumers to guess. Identify the single most consequential fracture line in your ecosystem.

Once that issue is visible, apply your entire toolkit - of which standards definition is only one part - to reliably improve it. That may be a standard. It might also be a reusable snippet, an improved template, a code generator, a linting rule, or a ten-minute walkthrough embedded in your onboarding. A standard is only one instrument in the toolkit, and often not the most effective one. [And if you are attempting to define standards without taking stock of the diverse array of levers for systems change at your disposal, stop what you're doing, and do that first.]

Once you've articulated the pain and created an approach (standards or not), then focus entirely on making that one improvement stick. Evangelize it. Validate it. Socialize examples of teams that applied it well. Integrate it into reviews, templates, and conversations. A governance program gains authority not from the volume of its standards but from the consistency of its outcomes.

Only after that single improvement holds should you widen the scope and choose the next issue. Progress in API governance is accumulative, not comprehensive. You build a navigable ecosystem the way you chart a coastline: one stretch at a time, at a scale that keeps the work actionable.

API ecosystems, like a coastline, are dynamic.

Coastlines are ever evolving. Tides shift, storms carve new channels, and erosion reshapes the familiar. They are stable enough to navigate year to year, but never static. The same is true of API ecosystems. New products launch, teams reorganize, technologies change, and patterns evolve. Any attempt to fully capture that landscape in a single, timeless document will fail for the same reason a perfect map of a living shoreline is impossible.

The goal of governance isn't to eliminate complexity; it's to provide enough shared structure that teams can move with confidence. That structure doesn't come from encyclopedic standards. It comes from choosing a sensible scale, improving one stretch of terrain at a time, and continuously returning to ask, "Where is the next place clarity would actually help?"

When you accept that the ecosystem is dynamic, the work becomes clearer. You stop chasing theoretical completeness and start investing in practical guidance that teams will actually use. Instead of mapping every jagged contour, you focus on creating reliable markers: the conventions, practices, and examples that help people find their way.

You'll never capture every detail of the coastline. But you can illuminate the parts that matter, and that's enough to keep the whole ecosystem moving in the right direction.

Milestones

A few incidental items that are worth a gander at the end of the year:

• QUERY (or a GET with a body) is now an official HTTP method! I used to encourage an overloaded post for use cases like this, places where including details in a query string was impractical, either because that information was too detailed or sensitive to be part of the URL. This new QUERY method helps with that. 
• There's a new release of aep.dev. Marsh Gardiner has some additional context.
• Media critic Jeff Jarvis is advocating for "APIs for news". The piece is light on technical details, which is understandable - he's addressing media decision makers, not technologists. While I do agree that disappearing quality information behind paywalls leaves the internet (and AI) to the propagandists and profiteers, the "gotta do it and figure out the business model later" isn't much strategic comfort. 

Wrapping Up

Would you look at the calendar? That is (almost) another year in the rear-view mirror. Thank you for reading not just this edition, but for your support through this past year. With all that's going on, I appreciate folks who are still doing the necessary work of sense-making. Hang in there, make sure to get some rest, and see you on the other side.

Till the next edition,

Matthew (@matthew in the fediverse and matthewreinbold.com on the web)