README.md

I/O Docs - Open Source in Node.js

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).

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

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.

"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.

"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.

"host" key value is the host name of
the API calls (should not include protocol or port number)

"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.

API-LEVEL CONFIG DETAILS

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.

Example #1 - Explanation of each field in an example API-level configuration