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

201–210 of 580 posts

Re: Most RESTful APIs aren't really RESTful

#201

Post by koolala »

shagie wrote: post #194
meehai wrote: post #193

Earlier quoted context omitted.

the last point got me. How can you idiomatically do a read only request with complex filters? For me both PUT and POST are "writable" operations, while "GET" are assumed to be read only. However, if you need to encode the state of the UI (filters or whatnot), it's preferred to use JSON rather than query params (which have length limitations). So ... how does one do it?

POST the filter, get a response back with the query to follow up with for the individual resources. POST /complex value1=something value2=else which then responds with 201 Created Location https://example.com/complex/53301a34-92d3-447d-ac98-964e9a8b3989 And then you can make GET request calls against that resource. It adds in some data expiration problems to be solved, but its reasonably RESTful.

Isn't this twice as slow? If your server was far away it would double load times?

Re: Most RESTful APIs aren't really RESTful

#202

Post by sahruum9 »

meehai wrote: post #193
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…

the last point got me. How can you idiomatically do a read only request with complex filters? For me both PUT and POST are "writable" operations, while "GET" are assumed to be read only. However, if you need to encode the state of the UI (filters or whatnot), it's preferred to use JSON rather than query params (which have length limitations). So ... how does one do it?

There was a proposal[1] a while back to define a new SEARCH verb that was basically just a GET with a body for this exact purpose.

[1]: https://www.ietf.org/archive/id/draft-ietf-httpbis-safe-meth...

Re: Most RESTful APIs aren't really RESTful

#203

Post by blueflow »

shagie wrote: post #194
meehai wrote: post #193

Earlier quoted context omitted.

the last point got me. How can you idiomatically do a read only request with complex filters? For me both PUT and POST are "writable" operations, while "GET" are assumed to be read only. However, if you need to encode the state of the UI (filters or whatnot), it's preferred to use JSON rather than query params (which have length limitations). So ... how does one do it?

POST the filter, get a response back with the query to follow up with for the individual resources. POST /complex value1=something value2=else which then responds with 201 Created Location https://example.com/complex/53301a34-92d3-447d-ac98-964e9a8b3989 And then you can make GET request calls against that resource. It adds in some data expiration problems to be solved, but its reasonably RESTful.

This has RESTful aesthetics but it is a bit unpractical if a read-only query changes state on the server, as in creating the uuid-referenced resource.

Re: Most RESTful APIs aren't really RESTful

#204

Post by ivan_gammel »

meehai wrote: post #193
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…

the last point got me. How can you idiomatically do a read only request with complex filters? For me both PUT and POST are "writable" operations, while "GET" are assumed to be read only. However, if you need to encode the state of the UI (filters or whatnot), it's preferred to use JSON rather than query params (which have length limitations). So ... how does one do it?

If you really want this idiomatically correct, put the data in JSON or other suitable format, zip it and encode in Base64 to pass via GET as a single parameter. To hit the browser limits you will need so big query that you may hit UX constraints earlier in many cases (2048 bytes is 50+ UUIDs or 100+ polygon points etc).

Pros: the search query is a link that can be shared, the result can be cached. Cons: harder to debug, may not work in some cases due to URI length limits.

Re: Most RESTful APIs aren't really RESTful

#205

Post by [deleted] »

myaccountonhn wrote: post #100
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?

https://htmx.org/ might be the closest attempt?

[deleted]

Re: Most RESTful APIs aren't really RESTful

#206

Post by pradn »

ralferoo wrote: post #154
pradn wrote: post #86

Earlier quoted context omitted.

I think you're right. APIs have a lot of aspects to them, so describing them is hard. API users need to know typical latency bounds, which error codes may be retried, whether an action is atomic or idempotent. HATEOAS gets you none of these things. So fully implementing a perfect version of REST is usually not necessary for most types of problems users actually encounter. What REST has given us is an industry-wide li…

I think this hits the nail on the head. Complaining that the current understanding of REST isn't exactly the same as the original usage is missing the point that now REST gives people a good idea of what to expect and how to use the exposed interface. It's actually a very analogous complaint to how object-oriented programming isn't how it was supposed to be and that only Smalltalk got it right. People now understand…

Yes, the field is littered with imperfection.

One thing though - if you do take the time to learn the original "perfect" versions of these things, it helps you become a much better system designer. I'm constantly worried about API design because it has such large and hard-to-change consequences.

On the other hand, we as an industry have also succeeded quite a bit! So many of our abstractions work really well.

Re: Most RESTful APIs aren't really RESTful

#207

Post by nsonha »

_heimdall wrote: post #98
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?

You realize that anyone using a browser to view HTML is using HATEOS, right? You could probably argue whether SPAs fit the bill, but for sure any server rendered or static site is using HATEOS. The point isn't that clients must have absolutely no prior knowledge of the server, its that clients shouldn't have to have complete knowledge of the server. We've grown used to that approach because most of us have been build…

HATEOAS is anything that serves the talking point now apparently

Re: Most RESTful APIs aren't really RESTful

#208

Post by ivan_gammel »

koolala wrote: post #201
shagie wrote: post #194

Earlier quoted context omitted.

POST the filter, get a response back with the query to follow up with for the individual resources. POST /complex value1=something value2=else which then responds with 201 Created Location https://example.com/complex/53301a34-92d3-447d-ac98-964e9a8b3989 And then you can make GET request calls against that resource. It adds in some data expiration problems to be solved, but its reasonably RESTful.

Isn't this twice as slow? If your server was far away it would double load times?

The response to POST can return everything you need. The Location header that you receive with it will contain permanent link for making the same search request again via GET.

Pros: no practical limit on query size. Cons: permalink is not user-friendly - you cannot figure out what filters are applied without making the request.

Re: Most RESTful APIs aren't really RESTful

#209

Post by kevindamm »

meehai wrote: post #193
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…

the last point got me. How can you idiomatically do a read only request with complex filters? For me both PUT and POST are "writable" operations, while "GET" are assumed to be read only. However, if you need to encode the state of the UI (filters or whatnot), it's preferred to use JSON rather than query params (which have length limitations). So ... how does one do it?

One uses POST and recognizes that REST doesn't have to be so prescriptive.

The part of REST to focus on here is that the response from earlier well-formed requests will include all the forms (and possibly scripts) that allow for the client to make additional well-formed requests. If the complex filters are able to be made with a resource representation or from the root index, regardless of HTTP methods used, I think it should still count as REST (granted, HATEOAS is only part of REST but I think it should be a deciding part here).

When you factor in the effects of caching by intermediate proxy servers, you may find yourself adapting any search-like method to POST regardless, or at least GET with params, but you don't always want to, or can't, put the entire formdata in params.

Plus, with the vagaries of CSRF protections, per-user rate-limiting and access restrictions, etc.,, your GET is likely to turn into a POST for anything non-trivial. I wouldn't advise trying for pure REST-ful on the merits of its purity.

Re: Most RESTful APIs aren't really RESTful

#210

Post by montroser »

naasking wrote: post #158
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…

HATEOAS adds lots of practical value if you care about discoverability and longevity.

Discoverability by whom, exactly? Like if it's for developer humans, then good docs are better. If it's for robots, then _maybe_ there's some value... But in reality, it's not for robots.

HATEOAS solves a problem that doesn't exist in practice. Can you imagine an API provider being like, "hey, we can go ahead and change our interface...should be fine as long as our users are using proper clients that automatically discover endpoints and programmatically adapt accordingly"? Or can you imagine an API consumer going, "well, this HTTP request delivers the data we need, but let's make sure not to hit it directly -- instead, let's recursively traverse a graph of requests each time to make sure this is still the way to do it!"

Post reply on HN