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 sent back in the response. It is not useful enough to know that something expects XML to be sent and returns XML; or JASN; or whatever. How do you document the data that gets sent in the request and the data sent back in the response?

Best I could find so far is the Enunciate tool where you can document your REST API and the data elements. Is Enunciate the right type of tool for this and am I missing out on any other tools that offer this that I should look at?

Consumers of my REST API can be in any language python, Java, .NET, etc

Answer 1

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

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

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 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.