REST is the architectural style that became synonymous with “API” for most of the modern era, the dominant approach to designing HTTP APIs, and the thing that, when people say “API,” they usually mean. Representational State Transfer — Roy Fielding’s name for the architectural style that makes the web work — is built on using HTTP as it was designed: resources identified by URLs, manipulated through standard methods (GET, POST, PUT, DELETE), with responses carrying representations of resource state and standard status codes communicating outcomes. REST won the API world because it was simpler, more accessible, and more aligned with how the web already worked than the heavyweight alternatives that preceded it. But my relationship with REST has always been pragmatic rather than dogmatic, and from a governance perspective, REST is interesting precisely because the question of what counts as “RESTful” became one of the most contentious and least productive debates in the entire field.
The foundational appeal of REST is that it uses the web as designed, and that’s where its governance value starts. I wrote about REST as a technology from the early days, defining it as a specific approach to API delivery built on HTTP’s native capabilities. The genius of REST is that it didn’t invent a new protocol layered on top of HTTP the way SOAP did — it embraced HTTP itself, using its verbs, its status codes, its content negotiation, its caching. This made REST APIs dramatically more accessible than their predecessors: any developer who understood the web understood the basics of REST. For governance, this matters because REST provides a shared vocabulary and set of conventions — methods, status codes, resource naming — that an organization can standardize around. A lot of API governance is fundamentally about enforcing consistent, correct use of these REST conventions across an organization’s APIs.
The “I believe in the web, not the dogma” position is the heart of my pragmatic view of REST, and it has real governance implications. I wrote in 2017 that I’m not a card-carrying RESTafarian, I just believe in the web — capturing my consistent stance that the value of REST is in using HTTP well, not in dogmatic adherence to a checklist of REST constraints. This matters for governance because the REST purism that demanded strict adherence to every architectural constraint — full HATEOAS, no RPC-style operations, header-based versioning, the whole orthodoxy — was often counterproductive, generating inconsistency and conflict rather than good APIs. I wrote pointedly in 2016 that shaming people for not being or understanding REST is why we have so much inconsistency in API design — because the gatekeeping and purism around REST drove people away from the shared conventions that would have produced consistency. Good governance promotes the useful, pragmatic conventions of REST without the dogmatic purism that alienates and fragments.
The “REST is a mess, just like us humans” framing captures the honest, mature view I’ve arrived at, and it’s deeply relevant to governing real APIs. I wrote in 2024 that REST is a mess, just like us humans — because real-world REST, the HTTP-and-JSON APIs that dominate the industry, are gloriously inconsistent, imperfect, and pragmatic rather than purely conformant to any specification. And that’s fine. The messiness reflects the reality that REST is a style, not a strict standard, and that real organizations make pragmatic choices that deviate from the orthodoxy. Governance has to meet this reality where it is: the goal isn’t to force every API into theoretical REST purity, but to establish enough consistency — in naming, in method usage, in status codes, in error handling — that the organization’s APIs are coherent and usable. Governing REST APIs means promoting the pragmatic conventions that produce consistency and good developer experience, while accepting that real REST is messy and that the purist ideal is neither achievable nor necessary.
REST in the diverse-toolbox context is where governance gets its proper scope, and it’s a point I’ve made consistently. REST is dominant, but it’s not the only API style, and I’ve always placed it alongside hypermedia, GraphQL, gRPC, and event-driven approaches as one tool among several. “API is not just REST,” as I wrote in 2018 — meaning that a mature API practice and a mature governance practice account for the fact that different styles suit different needs. From a governance standpoint, this means recognizing that REST conventions apply to your REST APIs, but that the organization may also have GraphQL APIs, event-driven APIs, and gRPC services that need their own governance approaches. The governance challenge is multi-protocol: REST is the dominant style you’ll govern most, but it’s not the whole picture, and forcing non-REST APIs into REST governance is as much a mistake as the REST purism that demanded everything be strictly RESTful.
Where I’ve landed is that REST is the dominant, foundational, pragmatically-messy style that most API governance is built around — and that governing REST well means embracing its useful conventions while rejecting the dogmatic purism that made the REST debates so unproductive. REST won the API world by using the web as designed, giving the industry a shared, accessible vocabulary of resources, methods, and status codes. That shared vocabulary is exactly what makes REST governable: an organization can standardize around REST conventions to produce consistency across its APIs. But the value is in the pragmatic conventions, not in theoretical purity, and the most important governance lesson from the history of REST is that purism produces inconsistency by alienating people from the shared conventions, while pragmatic, inclusive promotion of good REST practices produces the consistency governance actually wants. REST is a mess, like everything humans build at scale, and good governance works with that messiness — establishing enough shared convention to make APIs coherent and usable, without pretending that strict REST conformance is either achievable or the actual goal. The goal is good, consistent, usable APIs, and REST’s pragmatic conventions — used well rather than dogmatically enforced — are how most organizations get there. Believe in the web, govern toward consistency, skip the dogma, and accept the mess: that’s the pragmatic governance of REST that fifteen years of watching the REST debates has taught me is the right approach.
References
- API Technology: REST
- History Of APIs: NOAA APIs Have Been RESTful For Over 20 Years
- Shaming People For Not Being Or Understanding REST Is Why We Have So Much Inconsistency In API Design
- REST, Linked Data, Hypermedia, GraphQL, And gRPC
- I Am Not A Card-Carrying RESTafarian, I Just Believe In The Web
- API Is Not Just REST
- REST And Hypermedia And GraphQL And gRPC And Event-Driven
- REST Is A Mess, Just Like Us Humans
