- Carson Gross, creator of HTMX, argues in an essay that most JSON APIs do not fit Roy Fielding's definition of REST.
- His point is about where knowledge lives: in the server's reply, or copied into every client. He says the second route adds upkeep.
- Some Reddit commenters push back, citing apps with heavy local state. Ask your team which of your APIs serve only your own screens.
A word that hides a design choice
When engineers say "REST API", most mean a service that sends JSON over HTTP. Carson Gross, creator of the HTMX library, argues that this misreads the original idea. The name matters less than what it hides. It hides a decision about where knowledge of your data lives, and that decision shapes how much work each change creates.
Gross made the case in an essay on htmx.org. It walks through Chapter 5 of Roy Fielding's PhD thesis at U.C. Irvine, where the term REST began. Gross says REST describes the original web: clicking links, submitting forms, reading pages. In his telling, it was not written as a guide for JSON APIs.
One caution first. Gross built a tool around the approach he favors, so he is an interested party. The essay is an argument, not a measurement.
How the two designs differ
Gross uses a contact page at a single web address. The server returns HTML that holds the contact's details and links to edit, email or archive that contact. The browser knows nothing about contacts. It simply shows what it receives. The reply describes itself, including what the user can do next.
Gross lists the four constraints he takes from Fielding. Resources have addresses. They are changed through representations such as HTML pages. Messages describe themselves. And hypermedia, meaning the links and forms in the page, drives what happens next. In plain terms, the server's reply carries both the data and the next possible actions. If an action appears or disappears, new HTML arrives on the next page load.
Now compare a JSON reply. Gross grants that it is smaller. But the client must decide two things: how to display the data, and what actions are possible. The first is usually a template inside the client. The second usually means reading the API documentation and writing those rules into the client. Gross calls this the core difference. In the JSON design, knowledge about the resource sits inside every client.
Where the cost lands
Gross says the early web proved reliable and flexible because the client had little chance to break. He points to what followed the shift to JSON: more debate over versioning APIs and over general query features. He says this is "not accidental". He also says the hypermedia part of REST is usually ignored in JSON APIs.
The essay offers no figures on what this costs. The lesson here is a framing, not a verdict. Each client that carries rules about your data is another copy to update when those rules change. A web app, a mobile app and a partner integration are three copies. Whoever owns the schedule pays when they drift apart.
What the pushback says
Commenters on the Reddit thread, where a podcast host shared an interview with Gross, did not all agree. One commenter wrote that when you must update 12 widgets and keep local state, JSON is "the only game in town." Another said that anyone who used XML web services and SOAP 20 years ago is thankful for JSON over HTTP. A third called the whole critique "100% a semantics argument."
The host says the interview also covered when you actually need a single-page app. That suggests Gross does not claim HTML replies fit every product. We have not heard the episode, so treat that as the host's account. Gross's essay says there are pros and cons to both approaches and describes thick clients that keep a local store in sync with the back end as a different model. WebPulse's view is that a different model is not a broken one.
Questions to put to your team
The naming debate is for engineers. The spending question is yours.
First, which of our APIs serve only our own screens, and which serve outside partners? The answers carry different upkeep. Second, how many client versions run at once, and what does one change cost across all of them? Third, which screens truly need local state, and which only display records and offer a few actions? Fourth, when a vendor contract says "REST", what does the vendor mean, and what is the buyer promised?
The label is a matter of taste. Where each screen learns what it can do is a decision that carries a bill.
Produced by the WebPulse Newsroom with AI assistance from the original reporting credited below, and checked against that source by our editorial review. How we use AI.
Original reporting: htmx.org (Carson Gross).
