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

301–310 of 580 posts

Re: Most RESTful APIs aren't really RESTful

#301

Post by cryptonector »

kccqzy wrote: post #171
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…

It's not just the original REST that usually has no benefits. The industry's reinterpreted version of weak REST also usually has little to no benefits. Who really cares that deleting a resource must necessarily be done with the DELETE HTTP verb rather than simply a POST?

You have to represent the action somehow. And letting proxies understand a wee bit of what's going on is useful. That's how you can have a proxy that lets your users browse the web but not login to external sites, and so on.

Re: Most RESTful APIs aren't really RESTful

#302

Post by ivan_gammel »

troupo wrote: post #246
shadowgovt wrote: post #232

Earlier quoted context omitted.

How does the UI check if certain operations are available?

OPTIONS https://datatracker.ietf.org/doc/html/rfc2616 More links here: https://news.ycombinator.com/item?id=44510745

It’s something else. List of available actions may include other resources, so you cannot express it with pure HTTP, you need a data model for that (HAL is one of possible solutions, but there are others)

Re: Most RESTful APIs aren't really RESTful

#303

Post by guru4consulting »

ivan_gammel wrote: post #187
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…

>the HATEOAS detail ends up having no practical value and creates more problems than the ones it solves. Many server-rendered websites support REST by design: a web page with links and forms is the state transferred to client. Even in SPAs, HATEOAS APIs are great for shifting business logic and security to server, where it belongs. I have built plenty of them, it does require certain mindset, but it does make many th…

complexity

Re: Most RESTful APIs aren't really RESTful

#304

Post by cryptonector »

salmonellaeater wrote: post #30

Where this kind of API design is useful is when there is a user with an agent (e.g. a browser or similar) who can navigate the API and interact with the different responses based on their media types and what the links are called. Most web APIs are not designed with this use-case in mind. They're designed to facilitate web apps that are much more specific in what they're trying to present to the user. This is both de…

> Where this kind of API design is useful is when there is a user with an agent (e.g. a browser or similar) who can navigate the API and interact with the different responses based on their media types and what the links are called.

It's also useful when you're programming a client that is not a web page!

You GET a thing, you dereference fields/paths in the returned representation, you construct a new URI, you perform an operation on it, and so on.

Consider a directory / database application. You can define a RESTful, HATEOAS API for it, write a single-page web application for it -or a non-SPA if you prefer-, and also write libraries and command-line interfaces to the same thing, all using roughly similar code that does what I described above. That's pretty neat. In the case of a non-SPA you can use pure HTML and not think that you're "dereferencing fields of the returned representation", but the user and the user-agent are still doing just that.

Re: Most RESTful APIs aren't really RESTful

#305

Post by porridgeraisin »

ohdeargodno wrote: post #107
porridgeraisin wrote: post #64

Earlier quoted context omitted.

> RPC with status codes Yes. All endpoints POST, JSON in, JSON out (or whatever) and meaningful HTTP status codes. It's a great sweet spot. Of course, this works only for apps that fetch() and createElement() the UI. But that's a lot of apps. If I don't want to use an RPC framework or whatever I just do: { method: "makeBooking", argument: { one: 1, two: "too", }, ... } And have a dictionary in my server mapping metho…

>All endpoints POST This makes automating things like retrying network calls hell. You can safely assume a GET will be idempotent, and safely retry on failure with delay. A POST might, or might not also empty your bank account. HTTP verbs are not just for decoration.

> not just for decoration

Still, they are just a convention.

When you are retrying an API, you are calling the API, you know whether its a getBookings() or a addBooking() API. So write the client code based on that.

Instead of the API developer making sure GET /bookings is idempotent, he is going to be making sure getBookings() is idempotent. Really, what is the difference?

As for the benefits, you get a uniform interface, no quirks with URL encoding, no nonsense with browsers pre-loading, etc etc,. It's basically full control with zero surprises.

The only drawback is with cookies. Samesite: Lax depends on you using GET for idempotent actions and POST for unsafe actions. However, I am advocating the use of this only for "fetch() + createElement() = UI" kind of app, where you will use tokens for everything anyways.

Re: Most RESTful APIs aren't really RESTful

#306

Post by marcosdumay »

eadmund wrote: post #140
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-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.

Re: Most RESTful APIs aren't really RESTful

#307

Post by dwaltrip »

_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…

Can you be more specific? What exactly is the partial knowledge? And how is that different from non-conforming APIs?

Re: Most RESTful APIs aren't really RESTful

#308

Post by naasking »

mixedbit wrote: post #293
naasking wrote: post #273

Earlier quoted context omitted.

> There are many ideas in the REST paper that are super useful, but the goal of making a generic client working with any API is difficult if not impossible to achieve. It's definitely possible to achieve: anywhere that data is missing you present an input prompt, which is exactly what a web browser does. That said, the set of autonomous programs that can do something useful without knowing what they're doing is of co…

> 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 proves the point that the web browser is a generic hypermedia agent that changes behaviour based on hypermedia that's dictated solely by the URL.

You can start programming any app with a plain hypermedia version and then add JS to make the user experience better, which is the approach that HTMx is reviving.

Re: Most RESTful APIs aren't really RESTful

#309

Post by naasking »

shadowgovt wrote: post #235
naasking wrote: post #186

Earlier quoted context omitted.

> 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. Generic clients just need to understand hypermedia and they can discover your API, as long as your API returns hypermedia from its starting endpoint and all other endpoints are transitively lin…

> 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 behavior of the application to get tripped up on whether someone failed to close a tag.

This is such a non-issue. Why aren't you worried about badly formatted JSON? Because we have well-tested JSON formatters. In a world where people understood the value of hypermedia as an interchange format, we'd be in exactly the same position.

And to be clear, if JSON had links as a first class type rather than just strings, then that would qualify as a hypermedia format too.

Re: Most RESTful APIs aren't really RESTful

#310

Post by dwaltrip »

recursivedoubts wrote: post #168
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?

Yes. You used it to enter this comment. I am using it to enter this reply. The magical client that can make use of an auto-discoverable API is called a "web browser", which you are using right this moment, as we speak.

Wait what? So everything is already HATEOAS?

I thought the “problem” was that no one was building proper restful / HATEOAS APIs.

It can’t go both ways.

Post reply on HN