I/O Docs Community Edition in Node.js

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.

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.

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

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

(9). "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.

(10). "param" key value is the name of the parameter that
is added to an API request that holds the digital signature.

(11). "digest" key value is the digest algorithm that is used.
Values can be hex, base64 or binary.

(12). "location" (optional) key value sets where the signature will go in the request. Defaults to "header".

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

"base_uri" key value is the base website URL used in
the OAuth 2 dance. It is required.

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

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

"token" container instructs I/O Docs where to use the access/bearer token on requests. If the "location" is set
as the default token name when making calls with the
access token in the url query parameters. Not required if
"access_token" is used.

"param" is the parameter name for access token. This is valid only if the location value is "query"

"location" (optional) key value that sets where the bearer token will go. Acceptable values are: "header" and "query". If set to header, I/O Docs will follow the "Authorization: Bearer XXX" pattern. If set to "query", the name of the key will be dictated by the "param" value on line 13.

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"