Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

It's time to put REST to rest

sollecitom.github.io

Post reply on HN
Print view View original

51–60 of 85 posts

Re: It's time to put REST to rest

#51

Post by gweinberg »

stronglikedan wrote: post #17
JohnMakin wrote: post #11

> About being able to use a RESTful API directly from a browser: browsers only use the GET and POST HTTP methods, among the ones REST associates meaning to. You cannot use a RESTful API from the browser, because the PUT, PATCH, and DELETE methods are not used by the browser, and even the POST method cannot be used without a UI. Also, even if you could, APIs are for machines, not humans. The user experience would be d…

> without a specific UI for it None of my browsers seem to have PUT, PATCH, and DELETE baked into the standard UI (or even POST really), so maybe it is true?

I just checked the MDN docs https://developer.mozilla.org/en-US/docs/Web/HTML/Element/fo... The only allowed form methods are get, post, and dialog. So you can't do put, patch, or delete via a form.

Re: It's time to put REST to rest

#52

Post by alexpetros »

If the supposed benefits of REST are:

> 1) It’s simple, and easy to understand. You can perform the same actions on all resources, so you don’t need to learn the details of a specific API to use it. 2) The API is usable via a browser.

then the part that this article is missing is HTML. REST APIs require HTML (or equivalent), because (via the the browser) the HTML self-describes what actions can be performed on it. If you return `My Profile`, then the user knows that clicking on it will take them to their profile; they're interacting with the API without knowing its details.

A lot of people say "ah to hell with it REST has no meaning anymore" but since the premise of the article is to engage with the meaning of REST, well, that's kind of on them.

See the @recursivedoubts essays in another comment on this post too, they're much more in-depth than my comment.

Re: It's time to put REST to rest

#53

Post by recursivedoubts »

angilly wrote: post #15

As a REST enthusiast I was excited to read this and learn a new perspective but this section > The “benefits” REST is supposed to introduce Is one of the more egregious straw men I’ve seen in a while. Never once in my twenty years have I heard anyone say it’s nice because “you don’t have to read the docs” or “it works in a browser” REST helps with lots from thinking through clean data models to helping ensure consist…

The uniform interface, which is the defining characteristic of REST according to Roy Fielding[1], is what allows clients to interact with REST-ful APIs without "reading documentation":

> "A REST API should be entered with no prior knowledge beyond the initial URI (bookmark) and set of standardized media types that are appropriate for the intended audience (i.e., expected to be understood by any client that might use the API). From that point on, all application state transitions must be driven by client selection of server-provided choices that are present in the received representations or implied by the user’s manipulation of those representations. The transitions may be determined (or limited by) the client’s knowledge of media types and resource communication mechanisms, both of which may be improved on-the-fly (e.g., code-on-demand). [Failure here implies that out-of-band information is driving interaction instead of hypertext.]"

- https://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypert...

The missing piece here is hypermedia, which is a requirement for a REST-ful API, as Fielding notes again with frustration in the same essay.

[1] - https://ics.uci.edu/~fielding/pubs/dissertation/rest_arch_st...

Re: It's time to put REST to rest

#54

Post by camgunz »

nesarkvechnep wrote: post #38
simonw wrote: post #18

I agree with some of this - I've never found value in the different PUT/PATCH/etc verbs, and I think the lack of examples of good "pure" REST APIs indicates that pure REST doesn't work easily for most projects. I do think this throws away some pieces that are really valuable though: 1. URLs for concepts are a good idea 2. Distinguishing between read-only operations (which can be cached) and write operations using GET…

1. URLs doesn’t matter in REST because interactions are hypertext-driven. 2. The method to use is implied by the relationship of a link.

Implicating isn't a great way to document an API. You could easily do something you didn't intend to do, which could be no big deal or extremely costly.

Re: It's time to put REST to rest

#55

Post by jauntywundrkind »

I was pretty annoyed expecting some awful conclusion that we had to do something entirely different, resting upon what felt like extremely shaky grounds. A one-auarter decent OpenAPI will elaborate what endpoints do, which felt like all that was missing.

In the end though, the author isn't really arguing against what we have, expect they want /commands and /queries prefixes.

Given the way some endpoints can be overloaded with disparate behaviors, I don't disagree that sometimes it can be confusing for all the verbal to apply to an endpoint. But POST /students/enroll seems more than fine to me, and trying to wrestle out a new norm, where URLs aren't broken down by resource type but are broken down instead by behavior-class seems absurd & a folly.

> The fundamental issue with REST is that it defines operations that manipulate data structures. It’s about structure and structural changes, not behaviour. It’s imperative, rather than declarative.

If it's about structure, wouldn't that be declarative? Aren't behaviors typically imperative (move this here, drive that there)?

Re: It's time to put REST to rest

#56

Post by hn_throwaway_99 »

While I think some folks are getting caught up in the details, I thought the overall premise of this article was correct:

1. First, as other comments here are pointing out, in the industry people use "REST" to mean lots of different things. Some folks just use it to basically mean "An API over HTTP that uses JSON and HTTP methods (GET, POST, etc.)". For clarification I like to refer to that as "REST-lite". The author is talking about what I like to refer to has "true REST", which is strict about entities, verbs, etc. and the format of calls like PATCH.

2. I think the authors general points about why "true REST" is usually a bad idea have been proven out, and like most bad ideas that originated around that time period, they came about because people had a fantasy idea of how we would interact with resources on the web that wasn't born out in reality. I essentially thought his point about "being able to use any API without understanding it first" was spot on. I also think there were other good points about the supposed benefits that nobody really uses, or that aren't that much of a benefit (these days, who really cares about supporting multiple formats of an API like XML in addition to JSON?).

At the end of the day, after decades in software development, I've pretty much come to the conclusion that if your API framework doesn't look like some flavor of RPC, it's bad. This is just fundamentally how most software developers think: "I want to do some operation X, so just let me make a remote procedure call that is named X". This higher-order structure is usually a mistake that's trying to get developers to conform to some ivory tower way of thinking that doesn't work.

Re: It's time to put REST to rest

#57

Post by benrow »

ilovefood wrote: post #43

The article is good, and I get the point. However, from experience, this: > POST on /queries/enlisted-students-on-joining-date/version/1 { "date": "2023-09-22" } to retrieve all students that joined on a given date. always ends up in a complete and absolute mess, where every possible query gets it's own random name, different parameters, ending up with duplicates all over the place. Also, while it can be possible to…

I like the convention:

- 404 if resource requested by id

- 200 with empty list of results if it was a 'search' type request with params (not referring directly to an id)

Re: It's time to put REST to rest

#58

Post by ilaksh »

People will still be arguing about this in ten or twenty years when many new services use AI agents on a blockchain that automatically pick up DSLs invented a few days before by other AI agents and use them to negotiate and execute service orders on your behalf.

Eventually you may get something like a high dimensional protocol used for converting and syncing neural adapters on the fly, enabling "multi-brains" to collaborate opportunistically. But even then there will _still_ be people having this exact same argument.

Anyway, I feel like a lot of people actually moved on to GraphQL years ago. I think I probably need to catch up to that trend still.

Re: It's time to put REST to rest

#59

Post by Kwpolska »

> So when the server receives a PATCH /schools/{school-ID}/students/234 { "lastname": "Luthor" } request, it needs to understand that a student has requested for their lastname to be changed, and it then needs to decide what to do about it. What if some fields cannot be changed? What if the value of some fields is constrained by the value of some other fields? By allowing an arbitrary PATCH operation, these concepts are hard to model and validate requests against.

If there are validation issues with user-provided data in a PATCH, then the API should tell the user what they did wrong and reject the update, plain and simple. How would their solution react to bad data? How would it be different from what any implementation of PATCH does?

> POST on /queries/enlisted-students-on-joining-date/version/1 { "date": "2023-09-22" } to retrieve all students that joined on a given date.

So instead of a browser-accessible GET with idempotency standards, you need a POST and you need to serialize JSON just for a single field?

> POST on /commands/report-student-lastname-change/version/1 { "student-id": "123", "new-lastname": "Kent" } to report a lastname change for a student.

Great naming: I initially thought this would be about a report about last name changes, not a way to add new data.

Should there be separate endpoints for each field of each entity? That might replace “validation” of no changes to fields that cannot be changed, but it does not replace validation of last-name-is-not-empty or national-id-number-is-valid. What if the changes are provided in a form that allows to edit all data? Do I need to send separate commands for each user-edited field? If using the bulk form (POST /commands), what if one of the commands fails — will the previous commands be rolled back, or will the DB end up with partially-edited data?

> When a requested student is nonexistent, your API can return 200 OK HTTP status code with a { "user": null, "message": "No user exists with the specified ID" } response body.

And now you can’t even automatically detect error conditions and have consistent handling for them, at least not with a schema like this.

Post reply on HN