Permalink
Browse files

Merge remote-tracking branch 'upstream/master'

  • Loading branch information...
2 parents 19814e8 + d8f5732 commit c13acd9b9c365ab35de4fff7db3bd238cf24b3ef @adamkaplan committed May 1, 2012
Showing with 4,404 additions and 320 deletions.
  1. +1 −0 Procfile
  2. +199 −126 README.md
  3. +54 −24 app.js
  4. +4 −5 package.json
  5. +0 −157 public/data/alibris.json
  6. +17 −8 public/data/apiconfig.json
  7. +4,129 −0 public/data/linkedin.json
View
@@ -0,0 +1 @@
+web: node app.js
View
325 README.md
@@ -12,7 +12,6 @@ I/O Docs is a live interactive documentation system for RESTful web APIs. By def
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](https://github.com/mashery/iodocs)
-You can find a demo of it running here: [http://iodocs.demo.mashery.com](http://iodocs.demo.mashery.com)
However, we recommend that you install I/O Docs with *npm*, the Node package manager. See instructions below.
@@ -43,12 +42,13 @@ From the command line type in:
These will be automatically installed when you use any of the above *npm* installation methods above.
1. [express](http://expressjs.com/) - framework
-2. [oauth](https://github.com/unscene/node-oauth) - oauth library
+2. [oauth](https://github.com/ciaranj/node-oauth) - oauth library
3. [redis](https://github.com/mranney/node_redis) - connector to Redis
3. [connect-redis](https://github.com/visionmedia/connect-redis) - Redis session store
-4. [hashlib](https://github.com/brainfucker/hashlib) - used for signatures
-5. [querystring](https://github.com/visionmedia/node-querystring) - used to parse query string
-6. [jade](http://jade-lang.com/) - the view engine
+4. [querystring](https://github.com/visionmedia/node-querystring) - used to parse query string
+5. [jade](http://jade-lang.com/) - the view engine
+
+Note: hashlib is no longer a required module -- we're using the internal crypto module for signatures and digests.
RUNNING I/O DOCS
----------------
@@ -60,69 +60,69 @@ QUICK API CONFIGURATION EXAMPLE
-------------------------------
Adding an API to the I/O Docs configuration is relatively simple.
-1. Append the new top-level service information to the
- "./public/data/apiconfig.json" file.
-
- Example:
- <pre>
- "lowercaseapi": {
- "name": "Lower Case API",
- "protocol": "http",
- "baseURL": "api.lowercase.sample.com",
- "publicPath": "/v1",
- "auth": "key",
- "keyParam": "api_key_var_name"
- }
- </pre>
-
-2. Add the file "./public/data/lowercaseapi.json" to define the
- API.
-
- Example:
- <pre>
- {
- "endpoints": [
+First, append the new top-level service information to the `./public/data/apiconfig.json` file.
+
+Example:
+
+```js
+"lowercaseapi": {
+ "name": "Lower Case API",
+ "protocol": "http",
+ "baseURL": "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:
+
+```js
+{
+ "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."
- }
- ]
- }
- ]
+ "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."
+ }
+ ]
+ }
+ ]
}
- ]
- }
- </pre>
+ ]
+}
+```
TOP-LEVEL SERVICE CONFIG DETAILS - apiconfig.json
-------------------------------------------------
The *apiconfig.json* file contains high-level information about an API.
### Example #1 - Explanation of each field in an example API config that uses basic key authentication:
-<pre>
-1. "lower": {
-2. "name": "My API",
-3 "protocol": "http",
-4. "baseURL": "api.lowercase.sample.com",
-5. "publicPath": "/v1",
-6. "auth": "key",
-7. "keyParam": "api_key_var_name"
-8. }
-</pre>
+```js
+"lower": {
+ "name": "My API",
+ "protocol": "http",
+ "baseURL": "api.lowercase.sample.com",
+ "publicPath": "/v1",
+ "auth": "key",
+ "keyParam": "api_key_var_name"
+}
+```
Line:
@@ -145,7 +145,7 @@ Line:
Ex: "/v1"
- In the Example #2 below, there is also "privatePath"
+ In the Example #3 below, there is also "privatePath"
which is used for endpoints behind protected resources.
6. "auth" key value is the auth method. Valid values can be:
@@ -163,29 +163,104 @@ Line:
---
-### Example #2 - Twitter API config that uses 3-legged OAuth
-
-<pre>
-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. }
-</pre>
+### Example #2 - Explanation of each field in an example API config that uses basic key authentication with signatures (signed call).
+
+```js
+"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:
+
+1. Handle of the API. It is used to pull up the client
+ interface in the URL:
+
+ Ex: http://127.0.0.1:3000/upper
+
+2. "name" key value is a string that holds the name
+ of the API that is used in the Jade template output.
+
+3. "protocol" key value is either *http* or *https*
+
+4. "baseURL" key value is the host name of
+ the API calls (should not include protocol)
+
+5. "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.
+
+6. "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
+
+7. "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"
+
+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. "sigParam" key value is the name of the query 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. Closing curly-bracket for the "signature" object
+
+13. Closing curly bracket for main object.
+
+
+---
+
+
+### Example #3 - Twitter API config that uses 3-legged OAuth
+
+```js
+"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:
@@ -276,49 +351,47 @@ You should look at the *./public/data/* directory for examples.
### Example #1 - Explanation of each field in an example API-level configuration
-<pre>
-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. }
-</pre>
+```js
+{
+ "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"
+ ],
+ "Description":"The type of cereal desired"
+ },
+ {
+ "Name":"skip_status",
+ "Required":"N",
+ "Default":"",
+ "Type":"boolean",
+ "Description":"If true, status not included"
+ }
+ ]
+ }]
+}
+```
Line:
Oops, something went wrong.

0 comments on commit c13acd9

Please sign in to comment.