> The main issue I have with this is I have had the "pleasure" of working with pretty stupid people implementing clients on my API. They easily get POST and GET requests mixed up, HTTP and HTTPS, whether or not the request should be authenticated. I don't want to add something else to confuse them even more...
Where does the madness end? Do you treat everything as though it were GET and stick the real method (and every other request header) in a query parameter? I think it's ok to assume a basic level of understanding of one of the best documented specs in computing.
What's your definition of "basic level of understanding"?
A public API is about 99% of what we (Crocodoc) offer. While designing the latest version of our API, I always erred on the side of staying true to REST principles. Fortunately there were others on our team that erred on the other side. The result is a happy medium that certainly veers from the canonical definition of REST but is arguably easier for Joe Developer to play with. Guess what...we still receive an incredible amount of support requests from developers getting stuck.
It's tempting (and fun) to build APIs "the right way" and use little tricks like putting versioning in the media type. However, that's pretty often at odds with product/user experience/business considerations. Why offer a product that only 10% or 20% of your customers are savvy enough to use?
Each to their own I guess. However personally I would rather not spend time tracking down a "bug" due to a client not consuming my API as documented. If I can make it easier for them to use, by not doing things the "correct" way, then I would rather do that.
Where does the madness end? Do you treat everything as though it were GET and stick the real method (and every other request header) in a query parameter? I think it's ok to assume a basic level of understanding of one of the best documented specs in computing.