11

Many questions have been posted and answered about REST / HTTP based APIs, etc, but none seem to have much information on the following question:

What tools are available/used to document a HTTP-RPC API? Which tools are the best?

A Similar question (specific to ASP.NET) from Jan 2009 can be found here, but with no answers.

I am in the process of developing several APIs both professionally and for personal projects (.NET MVC/OpenRasta, PHP, Coldfusion, etc..), and I haven't found anything in particular to help document these APIs. I am not looking for auto-generation based on code-parsing/scrubbing or anything like that. As you probably already know a RESTful/HTTP-based API should be client and platform agnostic; as such I would expect any documentation tool to be the same.

Features that a decent tool might have:

  • Specify URLs/URIs format/structure
  • Request/Response formats and methods (GET/POST/etc, XML/JSON/etc)
  • Categorize endpoints/API Calls (such as grouping several calls under Authentication)
  • Auto-generate static reference files/documentation like the examples below
  • Include examples, test-cases, etc

Here are some examples of what I consider decent API documentation/reference(s) look like:

http://dev.twitter.com/doc/post/statuses/destroy/:id

http://www.salesforce.com/us/developer/docs/api_rest/index.htm

http://www.flickr.com/services/api/

Community
  • 1
  • 1
Colin
  • 2,001
  • 13
  • 28
  • http://www.lunatech-labs.com/open-source/jax-doclets looks promising but I haven't used it myself. Also, it's Java-specific, though perhaps the ideas behind it will be ported to other languages... – Tyler Jun 06 '11 at 17:34
  • That would be great if I were using Java :P However, it would definitely be useful for future java projects, so thanks for the link! – Colin Jun 06 '11 at 17:40
  • 1
    I created a simple template for RESTful API documentations: https://github.com/berb/rest-doc-template Perhaps it is useful for you as well. If not, you might want to fork and it use it as foundation. – b_erb Jun 19 '11 at 08:22
  • Another great example of RESTful API Documentation: http://www.twilio.com/docs/api/rest/call – Nikola Petkanski Feb 11 '13 at 15:39
  • an article on some options: http://apievangelist.com/2014/01/16/api-design-do-you-swagger-blueprint-or-raml/ – JasonS Jul 03 '14 at 06:38

4 Answers4

8

SWAGGER is probably worth a look for you need. I use it for documenting REST entrypoints exposed by a java application using Jersey, but it looks like you can use it with other languages too.

Michael Zilbermann
  • 1,398
  • 9
  • 19
3

One of the reasons such a tool does not exist is because the documentation of a RESTful API should NOT include any of these items:

  • Specify URLs/URIs format/structure
  • Request/Response formats and methods (GET/POST/etc, XML/JSON/etc)
  • Categorize endpoints/API Calls (such as grouping several calls under Authentication)

RESTful API documentation is about documenting media types used and their associated application semantics. You should be looking to produce something that looks more like this.

The examples you have given are HTTP based RPC APIs which is why they require this type of endpoint documentation. They are RESTful in name only. Now, why people are not creating tools to automatically document HTTP based RPC APIs, I can't really tell you. Maybe it is because the people who are writing those APIs are so busy maintaining them that they don't have time to writing documentation tooling!

Darrel Miller
  • 139,164
  • 32
  • 194
  • 243
  • 1
    I understand you point, and I'm not looking to argue semantics, for exmaple http://en.wikipedia.org/wiki/Restful is pretty misleading on the subject. Personally I would distinguish a RESTful application and RESTful API as two different entities. However, in the interest of sanity, I will update my question to be more specific! – Colin Jun 06 '11 at 15:49
  • 6
    -1: Dogmatic potshots over practicality. REST APIs need documentation too. Which HTTP status codes am I expected to receive for purposes of validation? How is authentication handled? Which character set am I supposed to use? What does the payload look like? Are any parts of it optional? What kind of data do individual components accept? You note that these things, as application semantics, are worth documenting, but you seem to deny that a tool that can be used to easily document this should exist, taking it instead to mean that the existence of a tool means you've picked the wrong solution. – Jesper Feb 11 '13 at 10:12
  • @jesper Status code for the purpose of validation: 400. Authentication is handled however the www-authenticate header says it is. Either the media type or the link relation will tell you what the payload looks like. Charset? media type docs. Optional components, media type docs. If a tool can magically document it, then chances are you will end up with docs that say "GET /Customer to retrieve a Customer". Which IMHO is 100% redundant. In a RESTful system, discovery of resources should be dynamic, not in documentation. – Darrel Miller Feb 11 '13 at 14:18
  • @DarrelMiller: You must be talking about a different sort of REST API. [Twitter's API documents all of this](https://dev.twitter.com/docs/api/1.1/get/statuses/mentions_timeline). I totally agree that pseudo-documentation like that is completely worthless. That wasn't the original question though; it was "how do I affix justified documentation to my list of calls" which in a REST context would be a list of resources and allowed operations. REST is not limited to HATEOAS, where your points are a lot more applicable. – Jesper Feb 11 '13 at 15:55
  • @Jesper "REST is not limited to HATEOAS" Apparently the guy who invented the term doesn't agree: http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven – Darrel Miller Feb 11 '13 at 15:59
  • @DarrelMiller: I know what Roy Fielding's thesis says (and what Roy Fielding in general says). I also know what the majority of the (self-labelled) REST APIs in use do. I'm not saying I don't look forward to his future, but it's not here yet, and in the meantime we all have to deal with the systems in our surroundings that do exist. – Jesper Feb 11 '13 at 16:27
0

You should take a look at the Swagger application, as already mentioned by @zim2001. It has a Swagger-ui component, which is a simple html and javascript application reading the json data recorded by the backend application. There are adapters for number of languages, including php and java.

If you are using the Symfony2 framework for PHP, here's ready-to-use bundle for automatic generation of the RESTful service documentation:

One thing I don't like about such generators is the lack of translations, so if you want to provide the documentation of your API exposed over RESTful services on many languages - you cant.

Nikola Petkanski
  • 4,724
  • 1
  • 33
  • 41
0

After much research I have discovered this is no tool that does exactly what I want. There a number of tools that are very much a step in the right direction, but are often language specific, and do not generate HTTP API/RPC Reference documentation, but rather Code/Library/API reference documentation.

As a result I plan on creating the tool the I require/envision from scratch. If/when I have something to show I will update my answer.

Colin
  • 2,001
  • 13
  • 28