[dnomad]

> "A REST API should spend almost all of its descriptive effort in defining the media type(s) used for representing resources and driving application state, or in defining extended relation names and/or hypertext-enabled mark-up for existing standard media types. Any effort spent describing what methods to use on what URIs of interest should be entirely defined within the scope of the processing rules for a media type (and, in most cases, already defined by existing media types).

Arguably this is the problem: what Fielding is describing here has a well-known name: Object Oriented Analysis and Design. It's not at all clear why a new formalization was needed when we already have Objects. Resources have URIs, Objects have memory addresses. Resources have representations that are defined by content media types, Objects have behavior that are defined by -- types.

> POST /articles/{articleId}/publish , POST /articles/{articleId}/submit , ... etc.

Good ol' OOAD can avoid nonsense like this. It's immediately clear that the Resources identified by these URIs aren't real objects. If you want to talk Published Articles vs Submitted Articles you would introduce new types and new repositories.

The only way this makes any sense is:

POST /articles/published/ POST /articles/submitted/

Only now does 'GET /articles/published/{articleID}' make sense and we might think about what that content media type looks like vs submitted articles.

[pas]

It looks like this is a case of the stereotypical academization. Fielding looked at the Web, and abstracted it, and calls it REST Architecture.

And of course, the problem is that nobody sits down to just do a quick World Wide Web API for an app, or an internal corporate business-as-usual thingie. In fact since the original hypertext project at CERN no one every did it. We still use the same Web, incrementally transformed into what it is today, but still the same HTML, same Content-Types, and HTML1.0-like markup. All eaten and excreted by JavaScript of course, but that's a prime example of something incremental, and not exactly thought out.

Moreover, there's not much to say about media types driving interaction, because 99.9% of the Web is GET GET GET. And OPTIONS (due CORS) is driven by out-of-band conventions (defined in the Fetch and the amended XHR APIs, but not much to do with media types - but of course, CORS is more about fixing the leaky encapsulations of the communications interface/layer, not about the content [the high level state being transferred]).

[LoSboccacc]

> Fielding looked at the Web, and abstracted it, and calls it REST Architecture.

yeah the perfect rest protocol is the web and the perfect rest clients are the humans that navigate the action represented on the hypermedia.

that said, there's some value to be had in discoverability, even if rest grossly gloss over how to discover parameters for the action that the state holds.

[masklinn]

> that said, there's some value to be had in discoverability, even if rest grossly gloss over how to discover parameters for the action that the state holds.

There absolutely is and API systems like graphql have taken that to heart (playing with a graphql explorer is delightful).

But forcing all programmatic interactions through a "discoverability" layer is not useful, yet that's essentially what REST (as originally formalised) mandates.

[blowski]

I'm pretty sure that if I call `POST /articles/{articleId}/publish`, it will publish the article with ID `{articleId}`. Whereas I'm not sure how `/articles/published/` works.

[pas]

That's actually a REST feature. You have to interact with /articles/published to get its media type and then based on that you will know what you can do with it. The URI shouldn't matter. It could be /4234234/224234324/020121020/xxxxAAAAzzz but if the media type is "published articles" which is defined in the API spec, then you will know what to do with it.