Databases
StackOverflow2013
Postsdbo
POWhat is the best tool for documenting/generate reference for a RESTful/HTTP RPC API?
 

Note that there are some explanatory texts on larger screens.

plurals
  1. POWhat is the best tool for documenting/generate reference for a RESTful/HTTP RPC API?
    primarykey
    data
    text
    <p>Many questions have been posted and answered about REST / HTTP based APIs, etc, but none seem to have much information on the following question:</p> <p>What tools are available/used to document a HTTP-RPC API? Which tools are the best?</p> <p>A Similar question (specific to ASP.NET) from Jan 2009 can be found <a href="https://stackoverflow.com/questions/436506/whats-the-best-tool-to-manage-documentation-for-restful-api">here</a>, but with no answers.</p> <p>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 <em>API</em> should be client and platform agnostic; as such I would expect any documentation tool to be the same. </p> <hr> <p>Features that a decent tool might have:</p> <ul> <li>Specify URLs/URIs format/structure</li> <li>Request/Response formats and methods (GET/POST/etc, XML/JSON/etc)</li> <li>Categorize endpoints/API Calls (such as grouping several calls under Authentication)</li> <li>Auto-generate static reference files/documentation like the examples below </li> <li>Include examples, test-cases, etc</li> </ul> <hr> <p>Here are some examples of what I consider decent API documentation/reference(s) look like:</p> <p><a href="http://dev.twitter.com/doc/post/statuses/destroy/:id" rel="nofollow noreferrer">http://dev.twitter.com/doc/post/statuses/destroy/:id</a></p> <p><a href="http://www.salesforce.com/us/developer/docs/api_rest/index.htm" rel="nofollow noreferrer">http://www.salesforce.com/us/developer/docs/api_rest/index.htm</a> </p> <p><a href="http://www.flickr.com/services/api/" rel="nofollow noreferrer">http://www.flickr.com/services/api/</a></p>
    singulars
    1. PO
      singulars
      1. PTAnswer
    1. This table or related slice is empty.
    1. PTQuestion
    1. USCommunity
    1. USColin
    plurals
    1. PL
      singulars
      1. LTLinked
    1. PL
      singulars
      1. LTLinked
    1. This table or related slice is empty.
    1. PO
      singulars
      1. PTAnswer
    2. PO
      singulars
      1. PTAnswer
    3. PO
      singulars
      1. PTAnswer
    1. VO
      singulars
      1. POWhat is the best tool for documenting/generate reference for a RESTful/HTTP RPC API?
      1. This table or related slice is empty.
      1. VTUpMod
    2. VO
      singulars
      1. POWhat is the best tool for documenting/generate reference for a RESTful/HTTP RPC API?
      1. This table or related slice is empty.
      1. VTUpMod
    3. VO
      singulars
      1. POWhat is the best tool for documenting/generate reference for a RESTful/HTTP RPC API?
      1. This table or related slice is empty.
      1. VTModeratorReview
    1. COhttp://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...
      singulars
      1. POWhat is the best tool for documenting/generate reference for a RESTful/HTTP RPC API?
      1. USMatrixFrog
    2. COThat would be great if I were using Java :P However, it would definitely be useful for future java projects, so thanks for the link!
      singulars
      1. POWhat is the best tool for documenting/generate reference for a RESTful/HTTP RPC API?
      1. USColin
    3. COI 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.
      singulars
      1. POWhat is the best tool for documenting/generate reference for a RESTful/HTTP RPC API?
      1. USb_erb
 

Querying!

 
Guidance
A row detail

Detail views are divided into sections. All the information in the data section comes from columns in the selected row. The other sections display data from other, related rows.

Related data can be related in a to-one or a to-many fashion. Captions of data related in a to-many fashion link to a list view showing a filtered view of the table.

Try moving around until you find a non-empty to-many entry and click on the label to get to one. You can move back to the root by clicking on the database name in the header.

SQuiL has stopped working due to an internal error.

If you are curious you may find further information in the browser console, which is accessible through the devtools (F12).

Reload