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

121–130 of 580 posts

Re: Most RESTful APIs aren't really RESTful

#121

Post by thaumasiotes »

TekMol wrote: post #3

You know what type of API I like best? /draw_point?x=7&y=20&r=255&g=0&b=0 /get_point?x=7&y=20 /delete_point?x=7&y=20 Because that is the easiest to implement, the easiest to write, the easiest to manually test and tinker with (by writing it directly into the url bar), the easiest to automate (curl .../draw_point?x=7&y=20). It also makes it possible to put it into a link and into a bookmark. This is also how HN does i…

You're going to run into all kinds of security issues if you let GET endpoints have side effects.

Re: Most RESTful APIs aren't really RESTful

#122

Post by osigurdson »

k2xl wrote: post #102
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…

This is very true. Over my 15 years of engineering, I have never suffered_that_ much with integrating with an api (assuming it exists). So the lack of "HATEOaS" hasn't even been noticable for me. As long as they get most of the 400 status codes right (specifically 200, 401, 403, 429) I usually have no issuss integrating and don't even notice that they don't have some "discoverable api". As long as I can get the data…

It isn't clear that HATEOS would be better. For instance:

>>Clients shouldn’t assume or hardcode paths like /users/123/posts

Is it really net better to return something like the following just so you can change the url structure.

"_links": { "posts": { "href": "/users/123/posts" }, }

I mean, so what? We've create some indirection so that the url can change (e.g. "/u/123/posts").

Re: Most RESTful APIs aren't really RESTful

#123

Post by Sharlin »

jghn wrote: post #120
mrweasel wrote: post #112

Earlier quoted context omitted.

> As long as they get most of the 400 status codes right (specifically 200, 401, 403, 429) A client had build an API that would return 200 on broken requests. We pointed it out and asked if maybe it could return 500, to make monitoring easier. Sure thing, next version "Http 200 - 500", they just wrote 500 in the message body, return remained 200. Some developers just do not understand http.

Ive seen this a few times in the past but for a different reason. What would happen in these cases was that internally there’d be some cascade of calls to microservices that all get collected. In the most egregious examples it’s just some proxy call wrapping the “real” response. So it becomes entirely possible to get a 200 from the thing responding g to you but it may be wrapping an upstream error that gave it a 500.

Sometimes I wish HN supported emojis so I could reply with the throw-up one.

Re: Most RESTful APIs aren't really RESTful

#124

Post by anonymars »

lazyasciiart wrote: post #109
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…

Haha, our API still returns XML. At least, most of the endpoints do. Not the ones written by that guy who thinks predictability in an API is lower priority than modern code, those ones return JSON.

I present to you this monstrosity: https://stackoverflow.com/q/39110233

Presumably they had an existing API, and then REST became all the rage, so they remapped the endpoints and simply converted the XML to JSON. What do you do with the value construct? Map it to the name `$`!

Congratulations, we're REST now, the world is a better place for it. Off to the pub to celebrate, gents. Ugh.

I think people tend to forget these things are tools, not shackles

Re: Most RESTful APIs aren't really RESTful

#125

Post by [deleted] »

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…

[deleted]

Re: Most RESTful APIs aren't really RESTful

#126

Post by _heimdall »

What's often missed when this topic comes up is the question of who the back end API is intended for.

REST and HATEOAS are beneficial when the consumer is meant to be a third party that doesn't directly own the back end. The usual example is a plain old HTML page, the end user of that API is the person using a browser. MCP is a more recent example, that protocol is only needed because they want agents talking to APIs they don't own and need a solution for discoverability and interpretability in a sea of JSON RPC APIs.

When the API consumer is a frontend app written specifically for that backend, the benefits of REST often just don't outweigh the costs. It takes effort to design a more generic, better documented and specified API. While I don't like using tools like tRPC in production, its hugely useful for me when prototyping for much the same reason, I'm building both ends of the app and its faster to ignore separation of concerns.

edit: typo

Re: Most RESTful APIs aren't really RESTful

#127

Post by layer8 »

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?

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 representations or implied by the user’s manipulation of those representations.”

If the client application only understands media types and isn’t supposed to know anything about the interrelationships of the data or possible actions on it, and there is no user that could select from the choices provided by the server, then it’s not clear how the client can do anything purposeful.

Surely, an automated client, or rather its developer, needs a model (a schema) of what is possible to do with the API. Roy Fieldings doesn’t address that aspect at all. At best, his REST API would provide a way for the client to map its model to the actual server calls to make, based on configuration information provided by the server as “hypertext”. But the point of such an indirection is unclear, because the configuration information itself would have to follow a schema known and understood by the client, so again wouldn’t be RESTful in Roy Fielding’s sense.

People are trying to fill in the blanks of what Roy Fielding might have meant, but in the end it just doesn’t make a lot of sense for what REST APIs are used in practice.

Re: Most RESTful APIs aren't really RESTful

#128

Post by pradn »

ale wrote: post #119
pradn wrote: post #106

> REST isn’t about exposing your internal object model over HTTP — it’s about building distributed systems that behave like the web. I think I finally understand what Fielding is getting at. His REST principles boil down to allowing dynamic discovery of verbs for entities that are typed only by their media types. There's a level of indirection to allow for dynamic discovery. And there's a level of abstraction in sayi…

In what context would a user discover parts of a REST API dynamically?

In the simple (albeit niche) case, a UI could populate a list of buttons based on the URIs/verbs that the REST API returns. So the UI would be totally dynamic based on the backend - and so, work pretty generically across REST APIs.

But for a client, UI or otherwise, to make use of a dynamic set of URIs/verbs would require it to either look for a specific keyword (hard coding the intents it can satisfy) or be able to semantically understand the API (which is hard, requires a human).

Oddly, all this stuff is full circle with the AI stuff. The MCP protocol is designed to give AIs text-based descriptions of APIs, so they can reason about how to use them.

Re: Most RESTful APIs aren't really RESTful

#129

Post by lucideer »

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…

> - CRUD actions are mapped to POST/GET/PUT/DELETE

Agree on your other three but I've seen far too many "REST APIs" with update, delete & even sometimes read operations behind a POST. "SOAP-style REST" I like to call it.

Re: Most RESTful APIs aren't really RESTful

#130

Post by Cthulhu_ »

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…

HTTP/JSON API works too, but you can assume it's what they mean by REST.

It makes me wish we stuck with XML based stuff, it had proper standards, strictly enforced by libraries that get confused by things not following the standards. HTTP/JSON APIs are often hand-made and hand-read, NIH syndrone running rampant because it's perceived to be so simple and straightforward. To the point of "we don't need a spec, you can just see the response yourself, right?". At least that was the state ~2012, nowadays they use an OpenAPI spec but it's often incomplete, regardless of whether it's handmade (in which case people don't know everything they have to fill in) or generated (in which case the generators will often have limitations and MAYBE support for some custom comments that can fill in the gaps).

Post reply on HN