Most RESTful APIs aren't really RESTful • Hacker News Board

Re: Most RESTful APIs aren't really RESTful

#341

Post by bborud » Wed, Jul 09, 2025, 5:41 PM UTC

PaulHoule wrote: post #325

cjpearson wrote: post #40

I sympathize with the pedantry here and found Fielding's paper to be interesting, but this is a lost battle. When I see "REST API" I can safely assume the following: - The API returns JSON - CRUD actions are mapped to POST/GET/PUT/DELETE - The team constantly bikesheds over correct status codes and at least a few are used contrary to the HTTP spec - There's a decent chance listing endpoints were changed to POST to su…

Fielding won the war precisely because he was intellectually incoherent and mostly wrong. It's the "worse is better" of the 21st century. RPC systems were notoriously unergonomic and at best marginally successful. See Sun RPC, RMI, DCOM, CORBA, XML-RPC, SOAP, Protocol Buffers, etc. People say it is not RPC but all the time we write some function in Javascript like const getItem = async (itemId) => { ... } which does…

What RPC mechanisms, in your opinion, are the most ergonomic and why?

(I have been offering REST’ish and gRPC in software I write for many years now. With the REST’ish api generated from the gRPC APIs. I’m leaning towards dropping REST and only offering gRPC. Mostly because the generated clients are so ugly)

Re: Most RESTful APIs aren't really RESTful

#342

Post by HumblyTossed » Wed, Jul 09, 2025, 5:42 PM UTC

cle wrote: post #228

motorest wrote: post #144

Earlier quoted context omitted.

> I sympathize with the pedantry here and found Fielding's paper to be interesting, but this is a lost battle. Why do people feel compelled to even consider it to be a battle? As I see it, the REST concept is useful, but the HATEOAS detail ends up having no practical value and creates more problems than the ones it solves. This is in line with the Richardson maturity model[1], where the apex of REST includes all the…

For me the battle is with people who want to waste time bikeshedding over the definition of "REST" and whether the APIs are "RESTful", with no practical advantages, and then having to steer the conversation--and their motivation--towards more useful things without alienating them. It's tiresome.

Then let developer-Darwin win and fire those people. Let the natural selection of the hiring process win against pedantic assholes. The days are too short to argue over issues that are not really issues.

Re: Most RESTful APIs aren't really RESTful

#343

Post by mixedbit » Wed, Jul 09, 2025, 5:43 PM UTC

Balooga wrote: post #319

mixedbit wrote: post #275

Earlier quoted context omitted.

You describe how web pages work, web pages are intended for human interactions, APIs are intended for machine interaction. How a generic Python or JavaScript client can discover these APIs? Such clients will request JSON representation of a resource, because JSON is intended for machine consumption, HTML is intended for humans. Representations are equivalent, if you request JSON representations of a /users resource,…

> You describe how web pages work, web pages are intended for human interactions Exactly, yes! The first few sentences from Wikipedia... "REST (Representational State Transfer) is a software architectural style that was created to describe the design and guide the development of the architecture for the World Wide Web. REST defines a set of constraints for how the architecture of a distributed, Internet-scale hyperme…

Most web apps today use APIs that return JSON and are called by JavaScript. Can you use REST for such services or does REST require a switch to HTML representation rendered by the server where each interaction returns new HTML page? How such HTML representation can even use PUT and DELETE verbs, as these are available only to JavaScript code? What If I design a system where API calls can be made both from the web and from a command line client or a library? Should I use two different architecture to cover both use cases?

Re: Most RESTful APIs aren't really RESTful

#344

Post by smaudet » Wed, Jul 09, 2025, 5:45 PM UTC

cle wrote: post #228

motorest wrote: post #144

Earlier quoted context omitted.

> I sympathize with the pedantry here and found Fielding's paper to be interesting, but this is a lost battle. Why do people feel compelled to even consider it to be a battle? As I see it, the REST concept is useful, but the HATEOAS detail ends up having no practical value and creates more problems than the ones it solves. This is in line with the Richardson maturity model[1], where the apex of REST includes all the…

For me the battle is with people who want to waste time bikeshedding over the definition of "REST" and whether the APIs are "RESTful", with no practical advantages, and then having to steer the conversation--and their motivation--towards more useful things without alienating them. It's tiresome.

It was buried towards the bottom of the article, but the reason, to me:

Clients can be almost automatic with a HATEOS implementation, because it is a self describing protocol.

Of course, Open API (and perhaps to some extent now AI) also mean that clients don't need to be written they are just generated.

However it is important perhaps to remember the context here: SOAP is and was terrible, but for enterprise that needed a complex and robust RPC system, it was beginning to gain traction. HATEOS is a much more general yet simple and comprehensive system in comparison.

Of course, you don't need any of this. So people built APIs they did need that were not restfull but had an acronym that their bosses thought sounded better than SOAP, and the rest is History.

Re: Most RESTful APIs aren't really RESTful

#345

Post by homebrewer » Wed, Jul 09, 2025, 5:46 PM UTC

mort96 wrote: post #89

blueflow wrote: post #67

Earlier quoted context omitted.

> and people aren't "mediocre" just for using widely accepted words If you work off "widely accepted words" when there is disagreeing primary literature, you are probably mediocre.

So your view is that the person who coins a term forever has full rights to dictate the meaning of that term, regardless of what meaning turns out to be useful in practice and gets broadly accepted by the community? And you think that anyone who disagrees with such an ultra-prescriptivist view of linguistics is somehow a "mediocre programmer"? Do I have that right?

I have no dog in this fight, but 90% of technical people around me keep calling authentication authorization no matter how many times I explain the difference to those who even care to listen. It's misused in almost every application developed in this country.

Sometimes it really is bad and "everybody" can be very wrong, yes. None of us are native English speakers (most don't speak English at all), so these foreign sounding words all look the same, it's a forgivable "offence".

Re: Most RESTful APIs aren't really RESTful

#346

Post by mardifoufs » Wed, Jul 09, 2025, 5:46 PM UTC

PaulHoule wrote: post #325

cjpearson wrote: post #40

I sympathize with the pedantry here and found Fielding's paper to be interesting, but this is a lost battle. When I see "REST API" I can safely assume the following: - The API returns JSON - CRUD actions are mapped to POST/GET/PUT/DELETE - The team constantly bikesheds over correct status codes and at least a few are used contrary to the HTTP spec - There's a decent chance listing endpoints were changed to POST to su…

Fielding won the war precisely because he was intellectually incoherent and mostly wrong. It's the "worse is better" of the 21st century. RPC systems were notoriously unergonomic and at best marginally successful. See Sun RPC, RMI, DCOM, CORBA, XML-RPC, SOAP, Protocol Buffers, etc. People say it is not RPC but all the time we write some function in Javascript like const getItem = async (itemId) => { ... } which does…

I'm not super familiar with SOAP and CORBA, but how is SOAP any more coherent than a "RESTful" API? It's basically just a bag of messages. I guess it involves a schema, but that's not more coherent imo, since you just end up with specifics for every endpoint anyways.

CORBA is less "incoherent", but I'm not sure that's actually helpful, since it's still a huge mess. You can most likely become a lot more proficient with RESTful APIs and be more productive with them, much faster than you could with CORBA. Even if CORBA is extremely well specified, and "RESTful" is based more on vibes than anything specific.

Though to be clear I'm talking about the current definition of REST APIs, not the original, which I think wasn't super useful.

Re: Most RESTful APIs aren't really RESTful

#347

Post by Sohcahtoa82 » Wed, Jul 09, 2025, 5:53 PM UTC

mixedbit wrote: post #47

When I was working on my first HTTP-based API 13 years ago, based on many comments about true REST, I decided to first study what REST should really be. I've read Fielding's paper cover to cover, I've read RESTful Web Services Cookbook from O'Reilly and then proceeded to workaround Django idioms to provide REST API. This was a bit cargo cult thinking from my end, I didn't truly understand how REST would benefit my se…

> The vision of API that is self discoverable and that works with a generic client is not practical in most cases. [..] Fielding's paper doesn't provide a complete recipe for building self-discoverable APIs. It is an architecture, but the details of how clients should really discover the endpoints and determine what these endpoints are doing is left out of the paper. To make truly discoverable API you need to specify protocol for endpoints discovery, operations descriptions, help messages etc. Then you need clients that understand your specification, so it is not really a generic client

You said what I've thought about REST better than I could have put it.

A true implementation of a REST client is simply not possible. Any client needs to know what all those URLs are going to do. If you suddenly add a new action (like /cansofspam/123/frobnicate), a client won't know what to do with it. The client will need to be updated to add frobnication functionality, or else it just ignores it. At best, it could present a "Frobnicate" button.

This really is why nobody has implemented a REST server or client that actually conforms to Fielding's paper. It's just not realistic to have a client that can truly self-discover an API without being written to know what APIs to expect.

Re: Most RESTful APIs aren't really RESTful

#348

Post by mardifoufs » Wed, Jul 09, 2025, 5:53 PM UTC

marcosdumay wrote: post #306

eadmund wrote: post #140

Earlier quoted context omitted.

> I'll never understand why the HATEOAS meme hasn't died. > Is anyone using it? Anywhere? As I recall ACME (the protocol used by Let’s Encrypt) is a HATEOAS protocol. If so (a cursory glance at RFC 8555 indicates that it may be), then it’s used by almost everyone who serves HTTPS. Arguably HTTP, when used as it was intended, is itself a HATEOAS protocol. > What kind of magical client can make use of an auto-discovera…

> As I recall ACME (the protocol used by Let’s Encrypt) is a HATEOAS protocol. On this case specifically, everybody's lives are worse because of that.

I'm not super familiar with acme, but why is that? I usually dislike the HATEOS approach but I've never really seen it used seriously, so I'm curious!

Re: Most RESTful APIs aren't really RESTful

#349

Post by mixedbit » Wed, Jul 09, 2025, 5:59 PM UTC

naasking wrote: post #308

mixedbit wrote: post #293

Earlier quoted context omitted.

> Web browsers do exactly this! Browser provide generic execution environment, but the client code (JavaScript/HTML/CSS) is not generic. Calendar application and messaging application entry points provide application specific code for implementing calendar or messaging apps functions . I don't think this is what was proposed in the REST paper, otherwise we wouldn't have articles like 'Most RESTful APIs aren't really…

> but the client code (JavaScript/HTML/CSS) is not generic The HTML/hypermedia returned is never generic, that's why HATEOAS works at all and is so flexible. The "client" JS code is provided by the server, so it's not really client-specific (the client being the web browser here--maybe should call it "agent"). Regardless, sending JS is an optimization, calendars and messaging are possible using hypermedia alone, and…

What I don't get from this and some other comments in this thread, is that the argument seems to be that REST is practical, every web page is actually a REST app, it has one entry point, all the actions are discoverable by the user from this entry point, application specific JavaScript code is allowed by REST architecture. But then, why are there so many articles and posts (also by Fielding) that complain that people claim do be doing REST, but are actually not doing it?

In all these discussion, I didn't see an article that would actually show an example of a successful application that does REST properly, all elements of it.

Re: Most RESTful APIs aren't really RESTful

#350

Post by Spivak » Wed, Jul 09, 2025, 6:04 PM UTC

Sohcahtoa82 wrote: post #347

mixedbit wrote: post #47

When I was working on my first HTTP-based API 13 years ago, based on many comments about true REST, I decided to first study what REST should really be. I've read Fielding's paper cover to cover, I've read RESTful Web Services Cookbook from O'Reilly and then proceeded to workaround Django idioms to provide REST API. This was a bit cargo cult thinking from my end, I didn't truly understand how REST would benefit my se…

> The vision of API that is self discoverable and that works with a generic client is not practical in most cases. [..] Fielding's paper doesn't provide a complete recipe for building self-discoverable APIs. It is an architecture, but the details of how clients should really discover the endpoints and determine what these endpoints are doing is left out of the paper. To make truly discoverable API you need to specify…

> A true implementation of a REST client is simply not possible

Sure it is, it's just not very interesting to a programmer. It's the browser. That's why there was no need talk about client implementations. And why it's hypermedia driven. It's implicit in the description that it's meant to be discoverable by humans.

AirBnb rediscovered REST when they implemented their Server Driven UI Platform. Once you strip away all the minutiae about resources and URIs the fundamental idea of HATEOS is ship the whole UI from the server and have the client be generic (the browser). Now you can't have the problem where the frontend gets desynced with the backend.