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've experience using Enunciate which is great but I don't really like the clients that you can generate with it. On the other hand, I've been using swagger on my last projects and it seems to fit my needs, it's really cool you should give a try!

UPDATE 03/08/2016: Looks like you can use Enunciate to build swagger docs.
See this.

Answer 2

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.

Answer 3

The approach that I've decided on for my project is Enunciate. Seems to be the de facto standard for REST API documentation.

Answer 4

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.