Copyright 2012-2013 Mashery, Inc.
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.
- Node.js - server-side JS engine
- npm - node package manager
- Redis - key+value storage engine
Note: 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.
- Node.js - https://github.com/joyent/node/wiki/Installation
- npm (Node package manager) - https://github.com/isaacs/npm
- Redis - http://redis.io/download
From the command line type in:
git clone http://github.com/mashery/iodocs.git cd iodocs npm install
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.
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)
Point your browser to: localhost:3000
API definitions are, by default, stored in ./public/data/ and described by ./public/data/apiconfig.json. This can
be overridden in config.json by setting the "apiConfigDir" property.
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
Adding an API to the I/O Docs configuration is relatively simple.
First, append the new top-level service information to the ./public/data/apiconfig.json file.
Example:
"lowercaseapi": {
"name": "Lower Case API",
"protocol": "http",
"baseURL": "api.lowercase.sample.com",
"publicPath": "/v1",
"auth": "key",
"keyParam": "api_key_var_name",
"headers": {
"Accept": "application/json",
"Foo": "bar"
}
}Add the file ./public/data/lowercaseapi.json to define the API.
Example:
{
"endpoints": [
{
"name": "Resource Group A",
"methods": [
{
"MethodName": "Method A1",
"Synopsis": "Grabs information from the A1 data set",
"HTTPMethod": "GET",
"URI": "/a1/grab",
"RequiresOAuth": "N",
"parameters": [
{
"Name": "param_1_name",
"Required": "Y",
"Default": "",
"Type": "string",
"Description": "Description of the first parameter."
}
]
},
{
"MethodName": "Method A1 User",
"Synopsis": "Grabs information from the A1 data set for a specific user",
"HTTPMethod": "GET",
"URI": "/a1/grab/:userId",
"RequiresOAuth": "N",
"parameters": [
{
"Name": "param_1_name",
"Required": "Y",
"Default": "",
"Type": "string",
"Description": "Description of the first parameter."
},
{
"Name": "userId",
"Required": "Y",
"Default": "",
"Type": "string",
"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.
The apiconfig.json file contains high-level information about an API.
"lower": {
"name": "My API",
"protocol": "http",
"baseURL": "api.lowercase.sample.com",
"publicPath": "/v1",
"auth": "key",
"keyParam": "api_key_var_name",
"headers": {
"Accept": "application/json",
"Foo": "bar"
}
}Line:
-
Handle of the API. It is used to pull up the client interface in the URL:
-
"name" key value is a string that holds the name of the API that is used in the Jade template output.
-
"protocol" key value is either http or https
-
"baseURL" key value is the host name of the API calls (should not include protocol)
-
"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.
-
"auth" key value is the auth method. Valid values can be:
"key" - simple API key in the URI "oauth1" - OAuth 1.0/1.0a "" - no authentication -
"keyParam" key value is name of the query parameter that is added to an API request when the "auth" key value from (5) is set to "key".
-
"headers" object contains key value pairs of HTTP headers that will be sent for each request for API. These are static key/value pairs.
-
Closing curly-bracket ;)
Example #2 - Explanation of each field in an example API config that uses basic key authentication with signatures (signed call).
"upper": {
"name": "Upper API",
"protocol": "http",
"baseURL": "api.upper.sample.com",
"publicPath": "/v3",
"auth": "key",
"keyParam": "api_key_var_name",
"signature": {
"type": "signed_md5",
"sigParam": "sig",
"digest": "hex"
}
}Line:
-
Handle of the API. It is used to pull up the client interface in the URL:
-
"name" key value is a string that holds the name of the API that is used in the Jade template output.
-
"protocol" key value is either http or https
-
"baseURL" key value is the host name of the API calls (should not include protocol)
-
"publicPath" key value is the full path prefix prepended to all method URIs. This value often includes the version in RESTful APIs.
Ex: "/v3"
In the Example #3 below, there is also "privatePath" which is used for endpoints behind protected resources.
-
"auth" key value is the auth method. Valid values can be:
"key" - simple API key in the URI "oauth1" - OAuth 1.0/1.0a "" - no authentication -
"keyParam" key value is the name of the query parameter that is added to an API request when the "auth" key value from (5) is set to "key"
-
"signature" is a JSON object that contains the details about the API call signing requirements. The signature routine coded in app.js is a hash of the string concatenation of API key, API key secret and timestamp (epoch).
-
"type" key value is either signed_md5 or signed_sha256. More signature methods are available with crypto.js, but have not been included in the code as options.
-
"sigParam" key value is the name of the query parameter that is added to an API request that holds the digital signature.
-
"digest" key value is the digest algorithm that is used. Values can be hex, base64 or binary.
-
Closing curly-bracket for the "signature" object
-
Closing curly bracket for main object.
"twitter": {
"name": "Twitter API",
"protocol": "http",
"baseURL": "api.twitter.com",
"publicPath": "/1",
"privatePath": "/1",
"booleanTrueVal": "true",
"booleanFalseVal": "false",
"auth": "oauth",
"oauth" : {
"type": "three-legged",
"requestURL": "https://api.twitter.com/oauth/request_token",
"signinURL": "https://api.twitter.com/oauth/authorize?oauth_token=",
"accessURL": "https://api.twitter.com/oauth/access_token",
"version": "1.0",
"crypt": "HMAC-SHA1"
},
"keyParam": ""
}Line:
-
Handle of the API. It is used to pull up the client interface in the URL:
-
"name" key value is a string that holds the name of the API that is used in the Jade template output.
-
"protocol" key value contains either http or https, but you're welcome to try other protocols.
-
"baseURL" key value is the base URL that accepts the API calls (should not include protocol)
-
"publicPath" key value is the path prefix prepended to all method URIs for non-protected method resources. This value often includes the version in RESTful APIs.
Ex: "/v1", "/1", etc.
-
"privatePath" key value is the path prefix prepended to all method URIs for OAuth protected method resources. This value is most often the version in RESTful APIs.
Ex: "/v1", "/1", etc.
-
"booleanTrueVal" key value is the default value for true Boolean values that are sent in API requests. Some APIs are designed to accept a wide variety of true derivatives, but some are very strict about this value.
Ex: "true", "TRUE", "True", "t", "T", "1", etc. Default: "true"
-
"booleanFalseVal" key value is the default value for false Boolean values that are sent in API requests. Some APIs are designed to accept a wide variety of false derivatives, but some are very strict about this value.
Ex: "false", "FALSE", "False", "f", "F", "0", etc. Default: "false"
-
"auth" key value is set to "oauth" when OAuth is the authentication mechanism. Field is required.
-
"oauth" key value is a JSON object that contains the OAuth implementation details for this API. Field is required when "auth" value is "oauth".
-
"type" key value is the OAuth is the authorization flow used for this API. Valid values are "three-legged" (normal authorization flow) and "two-legged" (no authorization flow).
-
"requestURL" key value is the Request Token URL used in the OAuth dance (used in three-legged scenario).
-
"signinURL" key value is the User Authorization URL used in the OAuth dance (where the user is redirected to provide their credentials -- used in three-legged scenario).
-
"accessURL" key value is the Access Token URL used in the OAuth dance (used in three-legged scenario).
-
"version" key value is the OAuth version. As of I/O Docs v1.1, "1.0" is the only supported version. Note: use "1.0" for both 1.0 and 1.0A implementations.
-
"crypt" key value is the OAuth signature method. As of I/O Docs v1.1 "HMAC-SHA1" is the only supported signing method.
-
Closing curly bracket for "oauth" JSON object.
-
"keyParam" key value is blank when OAuth is the authentication method.
-
Closing curly bracket for main object.
"foursquare": {
"name": "Foursquare (OAuth 2.0 Auth Code)",
"protocol": "https",
"baseURL": "api.foursquare.com",
"publicPath": "",
"privatePath": "/v2",
"auth": "oauth2",
"oauth2": {
"type": "authorization-code",
"baseSite": "https://foursquare.com/",
"authorizeURL": "oauth2/authenticate",
"accessTokenURL": "oauth2/access_token",
"tokenName": "oauth_token",
"authorizationHeader":"N"
},
"keyParam":""
}Line:
-
Handle of the API. It is used to pull up the client interface in the URL:
-
"name" key value is a string that holds the name of the API that is used in the Jade template output.
-
"protocol" key value contains either http or https, but you're welcome to try other protocols.
-
"baseURL" key value is the base URL that accepts the API calls (should not include protocol)
-
"publicPath" key value is the path prefix prepended to all method URIs for non-protected method resources. This value often includes the version in RESTful APIs.
Ex: "/v1", "/1", etc.
-
"privatePath" key value is the path prefix prepended to all method URIs for OAuth2 protected method resources. This value is most often the version in RESTful APIs.
Ex: "/v1", "/1", etc.
-
"auth" key value is set to "oauth2" when OAuth2 is the authentication mechanism. Field is required.
-
"oauth" key value is a JSON object that contains the OAuth implementation details for this API. Field is required when "auth" value is "oauth".
-
"type" key value is the OAuth 2 authorization flow used for this API. Valid values are "authorization-code", "client_credentials", and "implicit", named for each grant found here: "http://tools.ietf.org/html/rfc6749".
-
"baseSite" key value is the base website URL used in the OAuth 2 dance. It is required.
-
"authorizeURL" key value is the url string used to retrieve the authorization token in the "authorization-code" OAuth 2 flow. This is not necessary in any other OAuth 2 flow.
-
"accessTokenURL" key value is the url string used to retrieve the access (Bearer) token in any OAuth 2 flow. This is required in all OAuth 2 flows.
-
"tokenName" key value if the API does not use "access_token" as the default token name when making calls with the access token in the url query parameters. Not required if "access_token" is used.
-
"authorizationHeader" must by "Y" if the access (Bearer) token is sent through the request header as "Authorization: Bearer access_token". Only required if this is the case.
-
Closing curly bracket for "oauth2" JSON object.
-
"keyParam" key value is blank when OAuth 2 is the authentication method.
-
Closing curly bracket for main object.
Additional Note: All redirect URIs for the Foursquare API & your Foursqare app must be set through the Foursquare developer site. For the iodocs Foursquare API test these URIs are : "http://localhost:3000/foursquare", "http://localhost:3000/oauth2Success/foursquare"
For the Rdio API test, beta access to their new API is necessary. The site for the beta API is: "http://www.rdio.com/developers/"
For every API that is configured in apiconfig.json a JSON config file must exist. You should look at the ./public/data/ directory for examples.
{
"name":"User Resources",
"methods":[
{
"MethodName":"users/show",
"Synopsis":"Returns extended user information",
"HTTPMethod":"GET",
"URI":"/users/show.json",
"RequiresOAuth":"N",
"parameters":[
{
"Name":"user_id",
"Required":"Y",
"Default":"",
"Type":"string",
"Description":"The ID of the user",
},
{
"Name":"cereal",
"Required":"Y",
"Default":"fruitscoops",
"Type":"enumerated",
"EnumeratedList": [
"fruitscoops",
"sugarbombs",
"frostedteeth"
],
"EnumeratedDescription": {
"fruitscoops": "Fruit Scoops (packed with fruit goodness)",
"sugarbombs": "Sugar Bombs (filled with sugar)",
"frostedteeth": "Frosted Teeth (sugar coating)"
},
"Description":"The type of cereal desired"
},
{
"Name":"skip_status",
"Required":"N",
"Default":"",
"Type":"boolean",
"Description":"If true, status not included"
}
]
}]
}Line:
-
"name" key holds the value of the Resource name. Methods are grouped into Resources.
-
"methods" key value is an array of JSON objects (each one being a method)
-
"MethodName" key value is a string that is displayed via the view template.
-
"Synopsis" key value is a short description of the method.
-
"HTTPMethod" key value can be either GET, POST, DELETE or PUT (all caps)
-
"URI" key value is the path to the method that is appended to the baseURL and the public/private path.
-
"RequiresOAuth" key value is either Y or N. If Y, the privatePath is used from the top-level config. If N, the publicPath is used from the top-level config.
-
"parameters" key value is an array of JSON objects (each one being a parameter)
-
"Name" key value is a string that contains the name of the parameter.
-
"Required" key value is either Y or N. If Y, the parameter will be output as bold.
-
"Default" key value is a string, containing a default value that will be automatically populated onto the form.
-
"Type" key value can be an arbitrary string that describes the variable type; however, the value is boolean or enumerated a drop-down (select) box will appear.
-
"Description" key value is a string, containing the description of the parameter.
-
"Type" key value is set to enumerated for this parameter.
-
"EnumeratedList" key value is an array of enumerated values that will render a drop-down (select box) on the form.
-
"EnumeratedDescription" key value is an object of enumerated values as keys, and their descriptions as values that will be displayed below the Description.
-
Each value in the list is a string.
-
"Type" key value is boolean that will render a drop-down (select box) on the form for true and false.
If you need any help with I/O Docs, you can reach out to us via the GitHub Issues page at:
http://github.com/mashery/iodocs/issues