Copyright 2011 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).
You can find the latest version here: https://github.com/mashery/iodocs You can find a demo of it running here: http://iodocs.demo.mashery.com
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
- hashlib - used for signatures
- querystring - used to parse query string
- jade - the view engine
- You will need to copy config.json.sample to config.json. The defaults will work, but feel free to change them.
- node ./app.js
- Point your browser to: http://localhost:3000
Adding an API to the I/O Docs configuration is relatively simple.
-
Append the new top-level service information to the "./public/data/apiconfig.json" file.
Example:
"lowercaseapi": { "name": "Lower Case API", "protocol": "http", "baseURL": "http://api.lowercase.sample.com", "publicPath": "/v1", "auth": "key", "keyParam": "api_key_var_name" }
-
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." } ] } ] } ] }
The apiconfig.json file contains high-level information about an API.
1. "lower": { 2. "name": "My API", 3. "baseURL": "http://api.lowercase.sample.com", 4. "publicPath": "/v1", 5. "auth": "key", 6. "keyParam": "api_key_var_name" 7. }
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.
-
"baseURL" key value is the base URL that accepts the API calls (must include protocol)
-
"publicPath" key value is the path prefix prepended to all method URIs. This value is most often the version in RESTful APIs.
Ex: "/v1", "/1", etc.
In the Example #2 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
-
"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"
-
Closing curly-bracket ;)
1. "twitter": { 2. "name": "Twitter API", 3. "protocol": "http", 4. "baseURL": "api.twitter.com", 5. "publicPath": "/1", 6. "privatePath": "/1", 7. "booleanTrueVal": "true", 8. "booleanFalseVal": "false", 9. "auth": "oauth", 10. "oauth" : { 11. "type": "three-legged", 12. "requestURL": "https://api.twitter.com/oauth/request_token", 13. "signinURL": "https://api.twitter.com/oauth/authorize?oauth_token=" 14. "accessURL": "https://api.twitter.com/oauth/access_token", 15. "version": "1.0", 16. "crypt": "HMAC-SHA1", 17. } 18. "keyParam": "", 19. }
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 (must include protocol)
-
"publicPath" key value is the path prefix prepended to all method URIs for non-protected method resources. This value is most often 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.
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.
1. { 2. { 3. "name":"User Resources", 4. "methods":[ 5. { 6. "MethodName":"users/show", 7. "Synopsis":"Returns extended user information", 8. "HTTPMethod":"GET", 9. "URI":"/users/show.json", 10. "RequiresOAuth":"N", 11. "parameters":[ 12. { 13. "Name":"user_id", 14. "Required":"Y", 15. "Default":"", 16. "Type":"string", 17. "Description":"The ID of the user", 18. }, 19. { 20. "Name":"cereal", 21. "Required":"Y", 22. "Default":"fruitscoops", 23. "Type":"enumerated", 24. "EnumeratedList": [ 25. "fruitscoops", 26. "sugarbombs", 27. "frostedteeth" 28. ], 29. "Description":"The type of cereal desired" 30. }, 31. { 32. "Name":"skip_status", 33. "Required":"N", 34. "Default":"", 35. "Type":"boolean", 36. "Description":"If true, status not included" 37. } 38. ] 39. ] 40. } 41. }
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.
-
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