Awareness is, to my mind, the single most underrated thing that APIs actually deliver. People talk about APIs in terms of integration, automation, revenue, and developer ecosystems, but underneath all of that is something more fundamental: the act of doing APIs forces you to become aware of what you actually have. You cannot expose a resource through an API until you’ve identified it, defined it, named it, and understood it. That requirement — that you know your own digital assets well enough to make them programmatically available — is a forcing function for organizational self-knowledge that almost nothing else in technology provides. Most organizations have no idea what they have. APIs are how they find out.
I tried to define this directly in 2017 in a post on API awareness, and what struck me even then was how much ground it covers. API awareness spans the entire lifecycle — knowing an API exists at all, and then its versions, paths, schema, SDKs, documentation, support, issues, change logs, roadmaps, monitoring, testing, performance, authentication, security, terms of service, privacy, licensing, logging, plans, partners, even investments and acquisitions and deprecations. Awareness doesn’t come easy. It takes time, and access to the right information and signals, often scattered across many entities and domains. You have to aggregate, filter, and rank those signals to actually develop and strengthen awareness. I compared it to financial literacy — a kind of understanding that everyone operating in this space should cultivate, because without it you’re making decisions blind.
The most vivid version of this for me has always been the “out of the shadows” idea, which I wrote about in 2015 when I brought my own IT infrastructure out of the shadows with an API-first approach. Going through that migration, I was reminded that one of the biggest security lapses in my own world was simply things not being known. Little scripts written here and there, jobs I hadn’t run in months, general code exhaust from years of operation — all of it living in the shadows, unaccounted for, and therefore a risk. Anything unknown is a liability precisely because you can’t reason about it, secure it, or decide what to do with it. The fix was to give myself a single doorway with a single approach to authentication and a complete map of my surface area using OpenAPI and APIs.json. Suddenly I could audit, monitor, deprecate, and secure the whole thing — not because the API added new capability, but because the discipline of doing APIs made me aware of what was actually there.
This is why I’ve long argued that you can’t manage, secure, or govern what you can’t see, and that APIs are the mechanism that makes seeing possible. The awareness problem at organizational scale is staggering. When I worked on web service inventory at the Department of Veterans Affairs in 2014, the dynamic was telling: each IT group knew about their own web services and couldn’t care less about anyone else’s, while the contractors were the only ones who actually knew where all the web services were across all the groups. The institution as a whole had no coherent awareness of its own digital footprint. That’s the normal state of large organizations, not the exception. The resources exist, but no one holds a complete picture, and the picture that does exist often lives with outside vendors rather than with the organization itself.
The deepest articulation of awareness as a forcing function is the Amazon story, the Bezos mandate. When Jeff Bezos ordered that all teams expose their data and functionality through service interfaces, with no exceptions and everything designed to be externalizable, he wasn’t just imposing an architecture. He was forcing every team to decouple, to define exactly what resources they had, and to make them available through an API. That definitional discipline is awareness. Before you can externalize a capability you have to know precisely what it is, where its boundaries are, and what it does. Amazon spent years building that internal awareness of its own resources, and AWS was the result of externalizing it. The mandate worked as a self-knowledge engine as much as a technical one — by 2006 Amazon had identified its essential digital assets, optimized their use internally, and could then expose them to the world precisely because it had become aware of what it had.
Awareness is related to observability, but I’ve been careful to keep them distinct. Observability is the technical property — the degree to which you can infer the internal state of a system from its external outputs, through monitoring, logging, testing, and metrics. Awareness is the human and organizational understanding that observability enables. You can instrument a system perfectly and still have an organization that is completely unaware of what that instrumentation reveals, because the data never reaches the people who need it or gets aggregated into actual understanding. I framed an API observability stack as being about wanting as much visibility and awareness into your operations as you possibly can get — but the visibility is the means and the awareness is the end. Observability without awareness is just data nobody is looking at. Awareness is what happens when the signals actually change what people know and do.
The awareness that APIs create cuts across the business and technical divide, which is one of its most valuable properties. APIs crack open the black box of IT and make it legible to people who aren’t engineers. I’ve described APIs as oxygen and sunlight — they provide visibility into things businesses, governments, and developers might prefer to keep hidden, and that sunlight is what makes accountability possible. Internally, the same effect aligns groups that previously operated with separate, partial pictures. When I write about the alignment that OpenAPI brings across the lifecycle, the precondition for that alignment is self-awareness — it takes real work and the right vantage point for an organization to see how its pieces fit together. The machine-readable contract becomes a shared object that business and technical stakeholders can both look at and finally have the same understanding of what exists.
This awareness scales up to capabilities, which is where my more recent thinking has gone. Knowing your APIs is one level of awareness; knowing your capabilities — what your organization is actually able to do, expressed in business terms — is a higher one. The work of defining capabilities is fundamentally awareness work: forcing the business and engineering sides to jointly articulate what the organization can do, with clear boundaries, in a way both groups understand. Most organizations are not aware of their own capabilities in any rigorous, documented form. They have tribal knowledge, partial maps, and a lot of assumptions. The discipline of defining capabilities, like the discipline of defining APIs, drags that latent knowledge into the open where it can be reasoned about, governed, and put to use.
The reason awareness belongs in the governance conversation is that you cannot govern what you are not aware of. Every governance activity — applying policy, enforcing standards, managing risk, ensuring compliance, eliminating redundancy, planning deprecation — depends on first knowing what exists. An organization that doesn’t know how many APIs it has, where they are, who owns them, what data they expose, and how they’re used cannot govern them in any meaningful way; it can only react when something breaks. Awareness is the precondition for governance, and APIs are the most reliable awareness-generating mechanism we have, because they refuse to let you stay vague. The endpoint either exists and is defined, or it doesn’t work. That intolerance for ambiguity is exactly why doing APIs makes you aware — of your infrastructure, your applications, your data, your operations, and ultimately of what your organization actually is and what it’s capable of.
References
- The Secret To Amazon’s Success: Internal APIs
- APIs Provide Much Needed Oxygen And Sunlight In Our World
- Taking Web Service Inventory At The Department Of Veteran Affairs
- Bringing My IT Infrastructure Out Of The Shadows With An API-First Approach
- Thinking About An API Observability Stack
- Trying To Define API Awareness
- From Awareness, Observability, To API Ratings
- Getting On The Same API Page
