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 am not sure if you are asking for a tool to assist you in this, or if you're asking what the best practice is (or both).

As far as best practices, the same things apply to REST documentation as other software documentation - provide a good landing page with breadth (ie, a list of your resources logically organized with a blurb about what they do and their URI) with drill-down pages that explain in depth what each one does, with examples. Twitter's REST API is very well documented and it should be a good model.

Twitter API main page

Sample drilldown of one resource

I really love that drilldown page. It lists all of the parameters you need, with a description of each one. It has a sidebar that lists the supported types. It has links to related pages and other pages with the same tag. It has a sample request and response.