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

21–30 of 580 posts

Re: Most RESTful APIs aren't really RESTful

#21

Post by TekMol »

jaapz wrote: post #6
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…

This is great for API's that only have a few actions that can be taken on a given resource. REST-API's then are especially suited for acting as a gateway to a database, to easily CRUD and fetch lists of information. The best API's I've seen mix and match both patterns. RESTful API endpoints for data, "function call" endpoints for often-used actions like voting, bulk actions and other things that the client needs to b…

Can you give an example of an endpoint where you would prefer a "RESTful API endpoint"?

Re: Most RESTful APIs aren't really RESTful

#22

Post by sublinear »

makeitdouble wrote: post #2

It felt easier going through the post after reading these bits near the end: > The widespread adoption of a simpler, RPC-like style over HTTP can probably attributed to practical trade-offs in tooling and developer experience > Therefore, simply be pragmatic. I personally like to avoid the term “RESTful” for the reasons given in the article and instead say “HTTP” based APIs.

Yeah but why cause needless confusion? The colloquial definition of "RESTful" is better understood as just something you defined using the OpenAPI spec. All other variants of "HTTP API" are likely hot garbage nobody wants anyway.

Re: Most RESTful APIs aren't really RESTful

#23

Post by TekMol »

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

If you type it into the URL bar, it will use GET. Surely you're not advocating mutating data with GET?

What's your problem with it?

Re: Most RESTful APIs aren't really RESTful

#24

Post by JimDabell »

thom wrote: post #13

I struggle to believe that any API in history has been improved by the developer more faithfully following REST’s strictures. The closest we’ve come to actually decoupled, self describing APIs is MCP, and that required inventing actual AIs to understand them.

The most successful API in history – the World-Wide Web – uses REST principles. That’s where REST came from. It was somebody who was involved in the creation of the early web who looked at it and wrote down a description of what properties of the web made it so successful.

Re: Most RESTful APIs aren't really RESTful

#25

Post by Zardoz84 »

makeitdouble wrote: post #2

It felt easier going through the post after reading these bits near the end: > The widespread adoption of a simpler, RPC-like style over HTTP can probably attributed to practical trade-offs in tooling and developer experience > Therefore, simply be pragmatic. I personally like to avoid the term “RESTful” for the reasons given in the article and instead say “HTTP” based APIs.

I prefer call it "REST-like" APIs

Re: Most RESTful APIs aren't really RESTful

#26

Post by Pooge »

TekMol wrote: post #23
Scarblac wrote: post #7

Earlier quoted context omitted.

If you type it into the URL bar, it will use GET. Surely you're not advocating mutating data with GET?

What's your problem with it?

That any bot crawling your website is going to click on your links and inadvertently mutate data.

Reading your original comment I was thinking "Sure, as long as you have a good reason of doing it this way anything goes" but I realized that you prefer to do it this way because you don't know any better.

Re: Most RESTful APIs aren't really RESTful

#27

Post by sublinear »

runeks wrote: post #15
pbreit wrote: post #11

Earlier quoted context omitted.

That’s pretty bad design. Only GETs should include a querystring. Links should only read, not create, update or delete.

> Only GETs should include a querystring. Why?

Because HTTP is a lot more sophisticated than anyone cares to acknowledge. The entire premise of "REST", as it is academically defined, is an oversimplification of how any non-trivial API would actually work. The only good part is the notion of "state transfer".

Re: Most RESTful APIs aren't really RESTful

#28

Post by Valulz »

leourbina wrote: post #12

This post follows the general, highly academic/dogmatic, tone that I’ve seen when certain folks talk about REST. Most of the article talks about what _not_ to do, and has very little details on how to actually do it. The idea of having client/server decoupled via a REST api that is itself discoverable, and that allows independent deployment, seems like a great advantage. However, the article lacks even the simplest e…

Agreed. I wish there was some examples to better understand what the author means. Like, in a web app, do i have any prior knowledge about the "_links" actions? Do I know that the server is going to return the actions "self" and "activate"? Is the idea to hide the routes from the user until the api call, but he should know that the api could return actions like "self", "activate" or "deactivate"? How do you communicate that an action requires a specific body? For example, the call activate is done in POST and expect a json body with a date inside. How do you tell that to the user?

Re: Most RESTful APIs aren't really RESTful

#29

Post by TekMol »

Pooge wrote: post #26
TekMol wrote: post #23

Earlier quoted context omitted.

What's your problem with it?

That any bot crawling your website is going to click on your links and inadvertently mutate data. Reading your original comment I was thinking "Sure, as long as you have a good reason of doing it this way anything goes" but I realized that you prefer to do it this way because you don't know any better.

If you rely on the HTTP method to authenticate users to mutate data, you are completely lost. Bots and humans can send any method they like. It's just a string in the request.

Use cookies and auth params like HN does for the upvote link. Not HTTP methods.

Re: Most RESTful APIs aren't really RESTful

#30

Post by salmonellaeater »

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 deliberate and valuable; app creators need to be able to control the presentation to achieve their apps' goals.

REST API design is for use-cases where the users should have control over how they interact with the resources provided by the API. Some examples that should be using REST API design:

  - Government portals for publicly accessible information, like legal codes, weather reports, or property records

  - Government portals for filing forms and other interactions

  - Open data initiatives like Wikipedia and OpenStreetmap
Considering these examples, it makes sense that policing of what "REST" means comes from the more academically-minded, while the detractors of the definition are typically app developers trying to create a very specific user experience. The solution is easy: just don't call it REST unless it actually is.
Post reply on HN