You see these all the time now and while some will claim the term has lost its original meaning, I think REST is way too nice to have diluted because a bunch of jimmies could not be arsed to RTFM.
So I wanted to whip up a blog post to show how to move this API from its current RPC like style, to being truly RESTful. Five hours in I realized it had grown out of control and would take me the entire day to complete… Since I do not have that kind of luxury and because others have already explained it so well, instead I will curate their efforts.
Discoverability. Jeremy H goes through how to consume a RESTful API in a way that concretizes the discovery aspect of REST. Media types, like
application/vnd.example.coolapp.apiIndex-v1+xml are defined by the API and these should be the major focus of the documentation.
RESTful criteria. Yours truly goes through the RESTful criteria.