Description

A tool to generate request and response data for any REST JSON based web api. The output is a .json file
per request/response for each resource.

This is in the very early stages of being developed but is being used to document a set of production
web apis so it should mature fairly quickly.

A sample using this api is @ https://apiwritersample.codeplex.com/

Details

The tool is run using node.js and is scripted using javascript. But of course, it can create documentation content for a web api written in any language or technology since it's only http requests.

For example, a simple resource script to get the list of discussions, create a discussion, get the discussion
that was just created and then delete the discussion that was just created.

The key here is the ability to write to a context in the callback. Below, we stuff away the id of the object
that was just created. Subsequent requests reference context data in the url ({createdId}). Requests are
run serially using async.js

    apiwriter.postJson('/discussions', {"title":"A discussion", "author":"me"},
        function(context, result) {
            context.createdId = result.responseBody.id;
        });

    apiwriter.postJson('/discussions', {"title":"Another discussion", "author":"me"});
    apiwriter.getJson('/discussions');

    apiwriter.getJson('/discussions/{createdId}');
    apiwriter.deleteJson('/discussions/{createdId}');


The api also supports supplying a prepare callback if you need to customize the request further.

This will create files ready for your documentation to consume:
POST__discussions.json
GET__discussions.json			
GET__discussions__createdId_.json
DELETE__discussions__createdId_.json


Output of the file will look like:
{
   "method": "POST",
   "resourceFormat": "/discussions",
   "requestUrl": "http://localhost:1099/api/discussions",
   "requestHeaders": {
      "Content-Type": "application/json",
      "Content-Length": 44
   },
   "requestBody": {
      "title":"Another discussion",
      "author":"me"
   },
   "statusCode": 200,
   "responseHeaders": {
      "x-powered-by": "Express",
      "content-type": "application/json; charset=utf-8",
      "content-length": "64",
      "date": "Sun, 19 May 2013 11:51:34 GMT",
      "connection": "keep-alive"
   },
   "responseBody": {
      "title": "Another discussion",
      "author": "me",
      "id": 8
   }
}

Last edited May 20, 2013 at 8:03 PM by bryanmacfarlane, version 15