Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Most RESTful APIs aren't really RESTful

florian-kraemer.net

Post reply on HN
Print view View original

131–140 of 580 posts

Re: Most RESTful APIs aren't really RESTful

#131

Post by Gormo »

the__alchemist wrote: post #99
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…

I use the term "HTTP API"; more general. Context, in light of your definition: In many cases labeled "REST", there will only be POST, or POST and GET, and HTTP 200 status with an error in JSON is used instead of HTTP status codes. Your definition makes sense as a weaker form of the original, but it it still too strict compared to how the term is used. "REST" = "HTTP with JSON bodies" is the most practical definition…

> HTTP 200 status with an error in JSON is used instead of HTTP status codes

I've seen some APIs that not only always return a 200 code, but will include a response in the JSON that itself indicates whether the HTTP request was successfully received, not whether the operation was successfully completed.

Building usable error handling with that kind of response is a real pain: there's no single identifier that indicates success/failure status, so we had to build our own lookup table of granular responses specific to each operation.

Re: Most RESTful APIs aren't really RESTful

#132

Post by VladVladikoff »

the__alchemist wrote: post #99
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…

I use the term "HTTP API"; more general. Context, in light of your definition: In many cases labeled "REST", there will only be POST, or POST and GET, and HTTP 200 status with an error in JSON is used instead of HTTP status codes. Your definition makes sense as a weaker form of the original, but it it still too strict compared to how the term is used. "REST" = "HTTP with JSON bodies" is the most practical definition…

>HTTP 200 status with an error in JSON is used instead of HTTP status codes

This is a bad approach. It prevents your frontend proxies from handling certain errors better. Such as: caching, rate limiting, or throttling abuse.

Re: Most RESTful APIs aren't really RESTful

#133

Post by Devilspawn6666 »

nchmy wrote: post #118
layer8 wrote: post #117

This doesn’t provide any good arguments for why Roy Fielding’s conception should be taken as the gospel of how things should be done. At best, it points out that what we call REST now isn’t what Roy Fielding wanted. Furthermore, it doesn’t explain how Roy Fielding’s conception would make sense for non-interactive clients. The fact that it doesn’t make sense is a large part of why virtually nobody is following it.

Why doesn't fielding's conception make sense for non-interactive clients?

In a non-interactive case, what is supposed to be reading a response and deciding which links to do some something with or what to do with them?

Let's say you've got a non-interactive program to get daily market close prices. A response returns a link labelled "foobarxyz", which is completely different to what the API returned yesterday and the day before.

How is your program supposed to magically know what to do? (without your input/interaction)

Re: Most RESTful APIs aren't really RESTful

#134

Post by eadmund »

runroader wrote: post #66
ewuhic wrote: post #50

Earlier quoted context omitted.

[flagged]

This is more like people arguing over "proper" English, the point of language is to communicate ideas. I work for a German company and my German is not great but if I can make myself understood, that's all that's needed. Likewise, the point of an API is to allow programs, systems, and people to interoperate. If it accomplishes that goal, it's fine and not worth fighting over. If my API is supposed to rely on content-…

> This is more like people arguing over "proper" English, the point of language is to communicate ideas.

ur s0 rait, eye d0nt nnno wy ne1 b0dderz tu b3 "proppr"!!!!1!!

You are correct that communication is the point. Words do communicate a message. So too does disrespect for propriety: it communicates the message that the person who is ignorant or disrespectful of proper language is either uneducated or immature, and that in turn implies that such a person’s statements and opinions should be discounted if not ignored entirely.

Words and terms mean things. The term ‘REST’ was coined to mean something. I contend that the thing ‘REST’ originally denoted is a valuable thing to discuss, and a valuable thing to employ (I could be wrong, but how easy will it be for us to debate that if we can’t even agree on a term for the thing?).

It’s similar to the ironic use of the word ‘literally.’ The word has a useful meaning, there is already the word ‘figuratively’ which can be used to mean ‘not literally’ and a good replacement for the proper meaning of ‘literally’ doesn’t spring to mind: misusing it just decreases clarity and hinders communication.

> If my API is supposed to rely on content-type, how many different representations do I need? JSON is a given anymore, and maybe XML, but why not plain text, why not PDF?

Whether something is JSON or XML is independent of the representation — they are serialisations (or encodings) of a representation. E.g. {"type": "foo","id":1}, , 1 and (foo (id 1)) all encode the same representation.

Re: Most RESTful APIs aren't really RESTful

#135

Post by VladVladikoff »

impostervt wrote: post #114
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…

As long as it's not SOAP, it's great.

If I never have to use SOAP again in my life, I will die a happy man.

Re: Most RESTful APIs aren't really RESTful

#136

Post by enobrev »

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…

Sounds about right. I've been calling this REST-ish for years and generally everyone I say that to gets what I mean without much (any) explanation.

Re: Most RESTful APIs aren't really RESTful

#137

Post by Xenoamorphous »

OJFord wrote: post #87
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…

> I can safely assume [...] CRUD actions are mapped to POST/GET/PUT/DELETE Not totally sure about that - I think you need to check what they decided about PUT vs PATCH.

Isn't that fairly straightforward? PUT for full updates and PATCH for partial ones. Does anybody do anything different?

Re: Most RESTful APIs aren't really RESTful

#138

Post by nchmy »

Devilspawn6666 wrote: post #133
nchmy wrote: post #118

Earlier quoted context omitted.

Why doesn't fielding's conception make sense for non-interactive clients?

In a non-interactive case, what is supposed to be reading a response and deciding which links to do some something with or what to do with them? Let's say you've got a non-interactive program to get daily market close prices. A response returns a link labelled "foobarxyz", which is completely different to what the API returned yesterday and the day before. How is your program supposed to magically know what to do? (w…

Why does "your program" need to know anything? The whole point of hypermedia is that there isn't any "program" other than the web browser that agnostically renders whatever html it receives. If the (backend) "program" development team decides that a foobarxyz link should be returned, then that's what is correct.

I suspect that your misunderstanding is because you're still looking at REST as a crud api, rather than what it actually is. That was the point of this article, though it was too technical.

https://htmx.org/essays is a good introduction to these things

Re: Most RESTful APIs aren't really RESTful

#139

Post by nchmy »

layer8 wrote: post #127
nchmy wrote: post #118

Earlier quoted context omitted.

Why doesn't fielding's conception make sense for non-interactive clients?

Take this quote: “A REST API should be entered with no prior knowledge beyond the initial URI (bookmark) and set of standardized media types that are appropriate for the intended audience (i.e., expected to be understood by any client that might use the API). From that point on, all application state transitions must be driven by client selection of server-provided choices that are present in the received representat…

As I replied to the sibling comment, you're misunderstanding rest and hypermedia. The "schema" is html and the browser is the automated client that is exceptionally good at rendering whatever html the backend has decided to send.

Re: Most RESTful APIs aren't really RESTful

#140

Post by eadmund »

dwaltrip wrote: post #76

I'll never understand why the HATEOAS meme hasn't died. Is anyone using it? Anywhere? What kind of magical client can make use of an auto-discoverable API? And why does this client have no prior knowledge of the server they are talking to?

> 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-discoverable API? And why does this client have no prior knowledge of the server they are talking to?

LLMs seem to do well at this.

And remember that ‘auto-discovery’ means different things. A link typed next enables auto-discovery of the next resource (whatever that means); it assumes some pre-existing knowledge in the client of what ‘next’ actually means.

Post reply on HN