[angilly]

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 consistency within an API.

[recursivedoubts]

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...

[richbell]

> 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.

I've seen multiple people argue these points. shrug