Endpoints and methods are now links. When the url entered is a linked item, that item will be expanded upon page load.
Whatever term is typed into the search box, that term will be searched for in the json configuration file; API names (endpoint names) are not included in the search [probably something that should be changed].
This function was developed with the assumption that the starting input would be the main api file, which would look like the following:
{ "endpoints":
[...]
}The include statement syntax looks like this:
{
"external": {
"href": "./api_name/data.json",
"type": "list"
}
}{
"external": {
"href": "file:///user/home/api.json",
}
}"type": "list" is used only when the contents of the file to be included is a list object that will be merged into an existing list. An example would be storing all the get methods for an endpoint as a list of objects in an external file.
If one has a sufficiently large API that splitting it up would make it more manageable, perhaps it would be nice to have the API description stored in a seperate repository, and imported as a sub-module. (To my knowledge) git sub-modules can only exist in the top level directory of a project.
This feature allows you to define where to look for an API description file, beyond the default location of '/public/data/' in the IODocs installation directory.
Example configuration:
"requestbin": {
"name": "Requestb.in",
"protocol": "http",
"baseURL": "requestb.in",
"publicPath": "/",
"href": "file:///user/home/api/"
}Given the above configuration, when looking for the API description file, instead of looking in 'IODocs/public/data/', it will look in '/user/home/api'. This works well with the split configuration feature. If the 'href' property is not defined in the config file, the default location of 'IODocs/public/data/' will be used instead.
This feature is currently only setup for files on disk, but could be adapted to using descriptions located on the web as well.
Future functionality: { "href": "http://www.example.com/foo.json" } The function would return the parsed JSON data from foo.json, dealing with file retrieval from the web.
Content parameters show what can be entered for POST and PUT methods. When a method's parameters are filled out, the method's corresponding text area will show what the JSON form would look like.
Note: Perhaps there's a better term than 'content parameters', but I do not know it. I call them such as they appear under the word 'Content' in the display, and in the 'content' block in the api description file.
Note 2: 'content' and 'contentType' are two variables introduced in this fork by @dgc-wh to be able to send the content body as part of PUT and POST requests. 'content' replaces the 'requestBody' variable.
A few new types are introduced specifically for content parameters.
- collection - a list of objects belonging to a property. eg - "collection" : [{ "prop": "val", "prop2": "val2" }, { "prop3": "val3", "prop4": "val4" }]
- object - a set of properties and values belonging to a single property. eg. - "obj" : { "prop": "val", "prop2": "val2" }
- list - a list of values belonging to a property. eg. - "list" : [ "val", "val2", "val3" ]
Here is an example api that shows usage of all of these new types.
{
"endpoints": [
{
"name": "Testing API",
"methods": [
{
"MethodName": "Modify an application",
"Synopsis": "Modify a single application | stub",
"HTTPMethod": "PUT",
"URI": "/application/:app_id",
"RequiresOAuth": "N",
"content": {
"schema":{"type":"string"},
"contentType":["application/json","application/xml"],
"parameters": [
{
"Name": "scan_schedule",
"Required": "N",
"Type": "object",
"Description": "| stub",
"parameters": [
{
"Name": "specs",
"Required": "N",
"Default": "",
"Type": "collection",
"Description": "",
"parameters": [
{
"Name": "type",
"Required": "N",
"Default": "",
"Type": "string",
"Description": ""
},
{
"Name": "cron_spec",
"Required": "N",
"Default": "",
"Type": "string",
"Description": ""
},
{
"Name": "duration",
"Required": "N",
"Default": "",
"Type": "integer",
"Description": "The unit of measure is 'seconds'."
}
]
},
{
"Name": "exclude_dirs",
"Required": "N",
"Type": "list",
"Description": "List of directories to be excluded. | stub",
"parameters": [
{
"Required": "N",
"Type": "string"
}
]
}
]
}
]
},
"parameters": [
{
"Name": "app_id",
"Required": "Y",
"Type": "integer",
"Description": "Application id of application to be modified. | stub"
}
]
}
]
}
]
} Copyright 2012 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
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
Note: hashlib is no longer a required module -- we're using the internal crypto module for signatures and digests.
- 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.
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."
}
]
}
]
}
]
}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.
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