How do you document a REST API?

Question

How do you document a REST API? Not just the documentation of what the resources are, but really what is the data that gets sent in the request and what the data is that gets se

Answer 1

I may be wrong, but it seems like you want something similar to a WSDL and XML Schema to document your API. I suggest reading Joe Gregorio's post on Do we need WADL? It has a good discussion on why not to use this approach for a REST API. If you don't want to read the entire article, the basic idea is that API-like documentation (i.e. WADL) will never be sufficient and will lead to brittle interfaces. Another good article is Does REST need a description language? It has a lot of good links to this type of discussion.

While his post gives you advice on what not to do, it doesn't really answer the question on what you should do. The big thing about REST is the idea of a uniform interface. In other words, GET, PUT, POST, and DELETE should do exactly what you think they should do. GET retrieves a representation of the resource, PUT updates, POST creates, and DELETE deletes.

The big question is then about describing your data and what it means. You can always go the route of defining an XML Schema or something similar and generate documentation from the schema. Personally, I don't find machine generated documentation all that useful.

In my humble opinion, the best data formats have extensive, human readable documentation with examples. This is the only way I know how to properly describe semantics. I like the use of Sphinx to generate this type of documentation.