Iodocs
Interactive API documentation system
Install / Use
/learn @mashery/IodocsREADME
I/O Docs Community Edition in Node.js
Copyright 2011-2014 Mashery, Inc.
MAJOR CHANGE LOG
2014-07-22 - Summer Release Feature Enhancements
This set of updates addresses several feature requests around POST/PUT calls. There are several other enhancements listed below. Note, if you are using a version of I/O Docs Community Edition that pre-dates this release, you will need to update your schema. The structure is similar in many ways, but the top level objects have been renamed, as well as many of the key names.
- Numerous schema changes and improvements
- Support for references
- Base paths and authorization moved from apiConfig to api{name}.json files
- More robust/extensible auth definition block
- POST/PUT request body capabilities added
- Array type and interface added for use in request body
- Size and order support
- Serialized JSON support
- Parameter location enhancements
- Placement in the query string, path or header
- Method form UI generation driven by Alpaca/jQuery
SYNOPSIS
I/O Docs is a live interactive documentation system for RESTful web APIs. By defining APIs at the resource, method and parameter levels in a JSON schema, I/O Docs will generate a JavaScript client interface. API calls can be executed from this interface, which are then proxied through the I/O Docs server with payload data cleanly formatted (pretty-printed if JSON or XML). Basic HTML text tags are enabled in the JSON schema.
You can find the latest version here: https://github.com/mashery/iodocs
However, we recommend that you install I/O Docs with npm, the Node package manager. See instructions below.
BUILD/RUNTIME DEPENDENCIES
- Node.js - server-side JS engine
- npm - node package manager
- Redis - key+value storage engine
Build note: If you're not using a package manager, Node and some of the modules require compiler (like gcc). If you are on a Mac, you will need to install XCode. If you're on Linux, you'll need to install build-essentials, or something equivalent.
Redis note: Redis is considered a runtime dependency. It is used to store OAuth information server side. If you are not implementing OAuth, redis is not required. You can simply remove the redis block from config.json. However, if you do implement OAuth down the road, you will need to use Redis, otherwise you will see 500 errors during the auth dance.
INSTALLATION INSTRUCTIONS FOR NODE, NPM & REDIS
- Node.js - https://github.com/joyent/node/wiki/Installation
- npm (Node package manager) - https://github.com/isaacs/npm
- Redis - http://redis.io/download
INSTALLATION INSTRUCTIONS FOR I/O DOCS
From the command line type in:
<pre> git clone http://github.com/mashery/iodocs.git cd iodocs npm install </pre>Node Module Dependencies
These will be automatically installed when you use any of the above npm installation methods above.
- express - framework
- oauth - oauth library
- redis - connector to Redis
- connect-redis - Redis session store
- querystring - used to parse query string
- jade - the view engine
- supervisor - restart node upon an error or changed javascript file
Note: hashlib is no longer a required module -- we're using the internal crypto module for signatures and digests.
RUNNING I/O DOCS
Create your config file by copying the default config:
cp config.json.sample config.json
The defaults will work, but feel free to change them.
Run a Redis instance:
redis-server
Start I/O Docs:
npm start (*nix, Mac OSX)
npm run-script startwin (Windows)
Start I/O Docs with a custom config file:
./node_modules/.bin/supervisor -e 'js|json' -- app --config-file ../config.json (*nix, Mac OSX)
supervisor -e 'js' -- app --config-file ../config.json (Windows)
Ideally, the --config-file arg would be possible to use with npm start, but until
npm issue #3494 is resolved, this is not supported.
Point your browser to: localhost:3000
CONFIGURING API DEFINITION LOCATION
API definitions are, by default, stored in ./public/data/ and described by ./public/data/"apiName".json and referenced by ./public/data/apiconfig.json. This can
be overridden in config.json by setting the "apiConfigDir" property.
BASIC AUTH FOR SERVER
Enabling HTTP basic authentication on the server is simple. By default, the username and password values are empty ("").
- Open up config.json
- Navigate down to the basicAuth object
- Add values for username and password within the object
QUICK API CONFIGURATION EXAMPLE
Adding an API to the I/O Docs configuration is relatively simple.
First, append the api name to the ./public/data/apiconfig.json file.
Example:
"lowercaseapi": {
"name": "Lower Case API"
}
Add the file ./public/data/lowercaseapi.json to define the API.
Example:
{
"name": "Lower Case API",
"description": "An example api.",
"protocol": "rest",
"basePath": "http://api.lowercase.sample.com",
"publicPath": "/v1",
"auth": {
"key": {
"param": "key"
}
},
"headers": {
"Accept": "application/json",
"Foo": "bar"
},
"resources": {
"Resource Group A": {
"methods": {
"MethodA1": {
"name": "Method A1",
"path": "/a1/grab",
"httpMethod": "GET",
"description": "Grabs information from the A1 data set.",
"parameters": {
"param1": {
"type": "string",
"required": true,
"default": "",
"description": "Description of the first parameter."
}
}
},
"MethodA1User": {
"name": "Method A1 User",
"path": "/a1/grab/{userId}",
"httpMethod": "GET",
"description": "Grabs information from the A1 data set for a specific user",
"parameters": {
"param1": {
"type": "string",
"required": true,
"default": "",
"description": "Description of the first parameter."
},
"userId": {
"type": "string",
"required": true,
"default": "",
"description": "The userId parameter that is in the URI."
}
}
}
}
}
}
}
By default the parameters are added to the query string. But if the URI contains a named variable, it will substitute the value in the path.
TOP-LEVEL SERVICE CONFIG DETAILS
The apiconfig.json file contains the name of an API to show upon initiation.
"lowercaseapi": {
"name": "Lower Case API"
}
The high-level information about an API is set in the config JSON file.
Example #1 - Explanation of each field in an example API config that uses basic key authentication:
{
"name": "Lower Case API",
"protocol": "rest",
"basePath": "http://api.lowercase.sample.com",
"publicPath": "/v1",
"auth": {
"key": {
"param": "key",
"location": "query"
}
},
"headers": {
"Accept": "application/json",
"Foo": "bar"
},
...
Line:
(1). "name" key value is a string that holds the name of the API that is used in the Jade template output. Also true in apiconfig.json.
(2). "protocol" key value is either rest or soap
(3). "basePath" key value is the host path of the API calls
(4). "publicPath" key value is the full path prefix prepended to all method URIs. This value often includes the version in RESTful APIs.
Ex: "/v1"
In the Example #3 below, there is also "privatePath"
which is used for endpoints behind protected resources.
(5). "auth" container holds the authorization information. If absent, API requires no authorization.
(6). The key value that describes the auth method. Valid values can be: "key" - simple API key in the URI "oauth" - OAuth 1.0/2.0 "" - no authentication
(7). "param" key value is name of the parameter that is added to an API request when the "auth" key value from (6) is set to "key".
(8). "location" (optional) key value sets where the api key will go in the request. Defaults to "query". supported values: "query" and "header".
(9). "headers" object contains key value pairs of HTTP headers that will be sent for each request for API. These are static key/value pairs.
Example #2 - Explanation of each field in an example API config that uses basic key authentication with signatures (signed call).
{
"name": "Lower Case API"
