[clhodapp]

My experience is that the design considerations within a system are different from the design considerations between systems. Specifically, noun-oriented APIs with few generic verbs tend to be extremely effective at:

1) Being relatively fast for external developers to come up to speed with

2) Allowing (and in fact pressuring) you to make non-breaking evolutions to your API without it devolving into a total mess of confusing semi-overlapping operations

3) (As a result of the other two) Minimizing the bidirectional communication needed between groups of developers

The major con is that they tend to require quite a bit more work and code to implement than operation-oriented APIs, especially when you are the only client.

Others will certainly have different opinions, but the view I've been forming over the last few years is that resource-oriented (noun-oriented) APIs should be considered the default for "external" interfaces, while operation-oriented APIs are much better-suited for "internal" interfaces. Do note that, in this model, deciding what is "internal" vs "external" should be an active design choice. It should be made based on your expectations for code ownership/control, communication frequency, and project structure.

[WClayFerguson]

One of the reasons Amazon was successful as a cloud hosting company, and offers all the services it does is because of the famous Bezos email/memo to the entire company saying every API has to be designed as if it were external facing (usable by 3rd parties).

I think what you are conflating is "good documentation" and "well designed APIs" as an attribute of REST, when it's really just an attribute of good engineering.

Engineers have used functional interfaces for decades and there's just nothing at all in REST that's any kind of improvement over functional. There's a reason "functional programming" is a thing and "nounical programming" isn't even a word.

[wolfgang42]

“Nounical programming” is only not a word because it’s called “object-oriented” instead.

[WClayFerguson]

And we also agree all objects (in OOP) are operated on by verbs (methods), but REST claims that using a predefined set of generic verbs is good. It isn't good.

Pick up any book on OOP and try to convert all the "operations" (method calls) in the book into CRUD methods for every code example in the book. It's doable from an information theoretic standpoint, but the book would become a completely unreadable clusterfk, for precisely the same reason that REST is so awkward. Doing an API with a predefined set of generic verbs is just silly.

[noblethrasher]

In response to the criticism of "noun-oriented" programming, check our this video: https://www.youtube.com/watch?v=BDPHfRuAFnU&feature=youtu.be....

It's worth watching from the beginning, but I've linked to the relevant timestamp (8:30).