| The HTTP spec exists to help you interact with resources in a specific way. In my experience, the "shoddy REST" the original commenter is talking about usually involves developers ignoring the design principles behind HTTP and trying to pretend like they can't or don't need to map their organization's domain model to HTTP's resource model. This typically happens because they either don't understand how to do this, don't have time, or think that the effort involved to rethink their model isn't worth the effort. What they end up with is a cobbled-together mess of endpoints that perform unintuitively specific functions constructed in the language of a system that wasn't designed to work that way. A really good example of this might be a blog API. Which is better? POST /entries/<id>/publish or PATCH /entries/<id> with a request body of { published: true } The POST seems more immediately intuitive to the API developers, because they can just add all publish-related tasks in the publish route handler or controller and call it a day. But the PATCH is more immediately intuitive to the API consumer, because they probably understand that entries have a "published" field (this gets more into hypermedia and semantics and beyond the scope of this post), and that PATCH allows them to change a field, and that if "published" is true then the entry is live. A good analogy is trying to construct your own special-purpose language using English words, but with totally new meanings and purposes for each word, then expecting to communicate with others in this language. It superficially looks like English, but cannot be understood without volumes of documentation explaining how it is different. |