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

311–320 of 580 posts

Re: Most RESTful APIs aren't really RESTful

#311

Post by reactordev »

motorest wrote: post #144
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 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…

I’m with you. HATEOAS is great when you have two independent (or more) enterprise teams with PMs fighting for budget.

When it’s just yours and your two pizza team, contract-first-design is totally fine. Just make sure you can version your endpoints or feature-flag new API’s so it doesn’t break your older clients.

Re: Most RESTful APIs aren't really RESTful

#313

Post by tgv »

troupo wrote: post #257
tgv wrote: post #159

Earlier quoted context omitted.

Do you care? From my point of view, post, put, delete, update, and patch all do the same. I would argue that if there is a difference, making the distinction in the url instead of the request method makes it easier to search code and log. And what's the correct verb anyway? So that's an argument that there may be too many request methods, but you could also argue there aren't enough. But then standardization becomes…

> From my point of view, post, put, delete, update, and patch all do the same. That's how we got POST-only GraphQL. In HTTP (and hence REST) these verbs have well-defined behaviour , including the very important things like idempotence and caching: https://github.com/for-GET/know-your-http-well/blob/master/m...

There's no point in idempotency for operations that change the state. DELETE is supposed to be idempotent, but it can only be if you limit yourself to deletion by unique, non-repeating id. Should you do something like delete by email or product, you have to use another operation, which then obviously will be POST anyway. And there's no way to "cache" a delete operation.

It's just absurd to mention idempotency when the state gets altered.

Re: Most RESTful APIs aren't really RESTful

#314

Post by SoftTalker »

hombre_fatal wrote: post #174
calvinmorrison wrote: post #157

Earlier quoted context omitted.

REST means, generally, HTTP requests with json as a result.

It also means they made some effort to use appropriate http verbs instead of GET/POST for everything, and they made an effort to organize their urls into patterns like `/things/:id/child/:child_id`. It was probably an organic response to the complexity of SOAP/WSDL at the time, so people harping on how it's not HATEOAS kinda miss the historical context; people didn't want another WSDL.

> instead of GET/POST for everything

Sometimes that's a pragmatic choice too. I've worked with HTTP clients that only supported GET and POST. It's been a while but not that long ago.

Re: Most RESTful APIs aren't really RESTful

#315

Post by shadowgovt »

naasking wrote: post #309
shadowgovt wrote: post #235

Earlier quoted context omitted.

> Generic clients just need to understand hypermedia Yikes. Nobody wants to implement a browser to create a UI for ordering meals from a restaurant. I'm pretty sure the reason we ended up settling on just tossing JSON blobs around and baking the semantics of them into the client is that we don't want the behavior of the application to get tripped up on whether someone failed to close a tag. (Besides: practically, for…

> Yikes. Nobody wants to implement a browser to create a UI for ordering meals from a restaurant. You don't need a full web browser. Fielding published his thesis in 2000, browsers were almost trivial then, and the needs for programming are even more trivial: you can basically skip any HTML that isn't a link tag or form data for most purposes. > baking the semantics of them into the client is that we don't want the b…

If I'm going to do HTML that isn't HTML then I might as well not do HTML, there's a lot of sharp edges in that particular markup that I'd prefer to avoid.

> Why aren't you worried about badly formatted JSON?

Because the json spec is much smaller than the HTML spec so it is much easier for the parser to prevalidate and reject invalid JSON.

Maybe I need to reread the paper and substitute "a good hypermedia language" for HTML conceptually, see if it makes more sense to me.

Re: Most RESTful APIs aren't really RESTful

#316

Post by renerick »

Htmx essays have already been mentioned, so here are my thoughts on the matter. I feel like to have a productive discussion of REST and HATEOAS, we must first agree on the basics. Repeating my own comment from a couple of weeks ago, H stands for hypermedia, and hypermedia is a type of media, that uses common format for representing some server-driven state and embedding hypermedia controls which are presented by back-end agnostic hypermedia client to a user for discoverability and interaction.

As such, JSON driven APIs can't be REST, since there is no common format for representing hypermedia controls, which means that there's no way to implement hypermedia client which can present those controls to the user and facilitate interactions. Is there such implmentation? Yes, HTML is the hypermedia, s and s are controls and browsers are the clients. REST and HATEOAS is designed for the humans, and trying to somehow combine it with machine-to-machine interaction results in awkward implementations, blurry definitions and overcomplication.

Richardson maturity model is a clear indication of those problems, I see it as an admission of "well, there isn't much practicality in doing proper REST for machine-to-machine comms, but that's fine, you can only do some parts of it and it's still counts". I'm not saying we shouldn't use its ideas, resource-based URLs are nice, using feature of HTTP is reasonable, but under the name REST it leads to constant arguments between the "dissertation" crowd and "the industry has moved on" crowd. The worst/best part is both those crowds are totally right and this argument will continue for as long as we use HTTP

Re: Most RESTful APIs aren't really RESTful

#317

Post by andoando »

eska wrote: post #108
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…

While I ask people whether they actually mean REST according to the paper or not, I am one of the people who refuse to just move on. The reason being that the mainstream use of the term doesn’t actually mean anything, it is not useful, and therefore not pragmatic at all. I basically say “so you actually just mean some web API, ok” and move on with that. The important difference being that I need to figure out the pec…

REST is pretty much impossible to adhere to for any sufficiently complex API and we should just toss it in the garbage

Re: Most RESTful APIs aren't really RESTful

#318

Post by shadowgovt »

ivan_gammel wrote: post #300
shadowgovt wrote: post #232

Earlier quoted context omitted.

How does the UI check if certain operations are available?

It’s literally in server response: { … resource model _links: { “delete” : { “href” : “.” } } In this example you receive list of permitted operations embedded in the resource model. href=. means you can perform this operation on resource self link.

Oh, interesting. So rather than the UI computing what operations should be allowed currently by, say, knowing the user's current role and having rules baked into it about the relationship between role and UI widgets, the UI can compute what motive should be in or simply off of explicit statements or capability from the server.

I can see some meat on these bones. The counterpoint is that the protocol is now chattier than it would be otherwise... But a full analysis of bandwidth to the client would have to factor that you have to ship over a whole framework to implement those rules and keep those rules synchronized between client and server implementation.

Re: Most RESTful APIs aren't really RESTful

#319

Post by Balooga »

mixedbit wrote: post #275
Balooga wrote: post #237

Earlier quoted context omitted.

> Fielding's paper doesn't provide a complete recipe for building self-discoverable APIs. But it does though. A HTTP server returns a HTTP response to a request from a browser. The request is a HTML webpage that is rendered to the user with all discoverable APIs visible as clickable links. Welcome to the World Wide Web.

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 hypermedia system, such as the Web, should behave." -- [1]

If you are desiging a system for the Web, use REST. If you are designing a system where a native app (that you create) talks to a set of services on a back end (that you also create), then why conform to REST principles?

[1] - https://en.wikipedia.org/wiki/REST

Re: Most RESTful APIs aren't really RESTful

#320

Post by dvtkrlbs »

ehutch79 wrote: post #282
recursivedoubts wrote: post #255

Earlier quoted context omitted.

Yes. You used such an api to post your reply. And I am using it as well, via the affordances presented by the mobile safari hypermedia client program. Quite an amazing system!

No. I was served HTML. not a json respoise that the browser discovered how to display.

html is the hateoas response
Post reply on HN