Nobody Understands REST or HTTP

A very good and comprehensive writing.

One thing that I cannot find mentioned neither in the article nor in comments, is the confusion related to the idea of state.

While REST is, by definition, stateless, it merely describes the session, not the manipulated data. There's no way to avoid, at least implicit, object's state. For example, if user's password is not empty, it means that the user already set the password.

More comprehensively, with /users/1/edit, or whatever, it is frequently expected to get a different validation error, depending on the flow, such as a paid account might require more billing related details than one without email confirmed.

Of course, it is a nightmare to maintain such matters implicitly. That's why Ruby on Rails plugins like acts_as_machine, and similar, come handy. They do provide an explicit description of the object's behaviour, easy to transform into documentation, depending on the current state.

The idea shows its full potential with multipage forms. Each step of the form might be described with a different state, stored in the state attribute, leaving the controller RESTful, and the model's validations easy to understand.

A yet another confusion comes with too close database mapping. To stick with Ruby on Rails, there is nothing preventing the developer from creating his own setters and getters, like def vattr=(); end; def vattrr(); end.

The framework passes the value of a virtual attribute, using params, to #update_attribute, and other methods, the same way it does for regular attributes created automatically from the database's schema.

Very frequently such attribute provides a much cleaner way to represent the model, rendering either the HTML or the API much more easier to write or understand.

I thought I finally had REST figured out until I read this.

Does anyone else see a diminishing return on pedantically following the REST-prescribed design and actually creating an API that people are familiar with out of the gate? I feel like if I followed this article to the T in my current design, anyone trying to integrate with it would spend so much time reading my API documentation just to figure out why they weren't getting an XML reply that it would stop being productive.

I am working on an API for imgscalr right now and I think I have it about 80% RESTful at the moment -- the parts I'm not doing is paying any attention to the headers either coming or going between client or server.

I'm using the more recent "classic" /path/object.{format}?arguments format that I have seen folks like Wordnik and Vimeo use.

It may not be purely RESTful, but it is intuitive and I can't help but think: "Remember 3-4 years ago when REST wasn't all the craze and no one knew what it was? The web still managed to function back then..."

I'm trying to mix some practicality in a bowl filled with "best practices" and come up with something that most people can stomach.

I hope I hit that mark, but we'll see. As far as I'm concerned I'm sticking with the versioned URLs because I find it more intuitive for endpoints that change, get renamed or are removed than slamming one inside of a mime type or header or even a query string param a la AWS.

Do you have any bits of this code open sourced?

The original stateless way has fault and partition tolerance baked right in. By breaking this convention you open yourself to a world of hurt, no matter how many band aid concepts you patch over it.

If you had ever designed or worked on a distributed system that needed to scale you wouldn't talk about adding servers and sharing state (distributed anything).

Sure distributing state is a fail-safe strategy - but not a scalable or performant one.