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
This is also how HN does it:
/vote?id=44507373&how=up&auth=...
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 be able to do, but you want the API to be in control of how it is applied.
> REST-API's then are especially suited for acting as a gateway to a database, to easily CRUD and fetch lists of information.
I don't disagree, but I've found (delivering LoB applications) that they are not homogenous: The way REST is implemented, right now, makes it not especially suitable for acting as a gateway to a database.
When you're free of constraints (i.e. greenfield application) you can do better (ITO reliability, product feature velocity, etc) by not using a tree exchange form (XML or JSON).
Because then it's not just a gateway to a database, it's an ill-specified, crippled, slow, unreliable and ad-hoc ORM: it tries to map trees (objects) to tables (relations) and vice versa, with predictably poor results.
Can you give an example of an endpoint where you would prefer a "RESTful API endpoint"?
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?
Bots, browsers that preload URLs, caching (both browser and backend and everything in between), the whole infrastructure of the Web that assumes GET never mutates and is always safe to repeat or serve from cache.
Using GET also circumvents browser security stuff like CORS, because again the browser assumes GET never mutates.
So why is there no problem with vote/flag/vouche on HN being GET endpoints?
Then that does not conform to the HTTP spec. GET endpoints must be safe, idempotent, cachable. Opening up a site to cases were web crawlers/scrapers may wreak havoc.
There is, it's bad. Luckily votes aren't very crucial.
Votes are crucial. HN goes to great lengths to prevent votes that do not stem from real user intent.
See this post for example:
https://news.ycombinator.com/item?id=22761897
Quotes:
"Voting ring detection has been one of HN's priorities for over 12 years"
"I've personally spent hundreds of hours working on this"
https://news.ycombinator.com/item?id=3742902
Indeed, user embedded pictures can fire GET requests while can not make POST requests. But this is not a problem if you don't allow users to embed pictures, or you authenticate the GET request somehow. Anyway GET requests are just fine.
The same would have worked with a POST endpoint.
The story url only would have to point to a web page that creates the upvote post request via JS.
That runs into CORS protections though.
CORS is a lot less strict around GET as it is supposed to be safe.
Nope, it would not have been prevented by CORS.
CORS prevents reading from a resource, not from sending the request.
If you find that surprising, think about that the JS could also have for example created a form with the vote page as the target and clicked on the submit button. All completely unrelated to CORS.
> CORS prevents reading from a resource
CORS does nothing of the sort. It does the exact opposite – it’s explicitly designed to allow reading a resource, where the SOP would ordinarily deny it.
Even mdn calls it "violating the CORS security rules" instead of SOP rules: https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/COR...
Anyway, this is lame low effort trolling for some unknown purpose. Stop 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.
You say that, but there are lots of security features like SameSite=Lax that are built on the assumption that GET requests are harmless.
> If you rely on the HTTP method to authenticate users to mutate data, you are completely lost
I don't know where you are getting that from but it's the first time I've heard of it.
If your link is indexed by a bot, then that bot will "click" on your links using the HTTP GET method—that is a convention and, yes, a malicious bot would try to send POST and DELETE requests. For the latter, this is why you authenticate users but this is unrelated to the HTTP verb.
> Use cookies and auth params like HN does for the upvote link
If it uses GET, this is not standard and I would strongly advise against it except if it's your pet project and you're the only maintainer.
Follow conventions and make everyone's lives easier, ffs.
There was a post about Garage opener I read here sometime back. https://news.ycombinator.com/item?id=16964907
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".
Not a REST API, but I've found it particularly useful to include query parameters in a POST endpoint that implements a generic webhook ingester.
The query parameters allow us to specify our own metadata when configuring the webhook events in the remote application, without having to modify our own code to add new routes.
I used to do that but I've been fully converted to REST and CRUD gang. Once you establish the initial routes and objects it's really easy mount everything else on it and move fast with changes. Also using tools like httpie it's super easy to test anything right in your terminal.
You're going to run into all kinds of security issues if you let GET endpoints have side effects.