Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 443 lines (329 sloc) 14.759 kB
d5bf45d @mansilladev Readme file added.
mansilladev authored
1 I/O Docs - Open Source in Node.js
2 =================================
3 Copyright 2011 Mashery, Inc.
00be40c @mansilladev README
mansilladev authored
4
6684279 @mansilladev README
mansilladev authored
5 [http://www.mashery.com](http://www.mashery.com)
00be40c @mansilladev README
mansilladev authored
6
d5bf45d @mansilladev Readme file added.
mansilladev authored
7 [http://developer.mashery.com](http://developer.mashery.com)
8
9 SYNOPSIS
10 --------
6684279 @mansilladev README
mansilladev authored
11 I/O Docs is a live interactive documentation system for RESTful web APIs. By defining APIs at the resource, method and parameter
12 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).
d5bf45d @mansilladev Readme file added.
mansilladev authored
13
14 You can find the latest version here: [https://github.com/mashery/iodocs](https://github.com/mashery/iodocs)
15
16 However, we recommend that you install I/O Docs with *npm*, the Node package manager. See instructions below.
17
18 BUILD/RUNTIME DEPENDENCIES
19 --------------------------
20 1. Node.js - server-side JS engine
21 2. npm - node package manager
22 3. Redis - key+value storage engine
23
24 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.
25
26 INSTALLATION INSTRUCTIONS FOR NODE, NPM & REDIS
27 -----------------------------------------------
28 1. Node.js - [https://github.com/joyent/node/wiki/Installation](https://github.com/joyent/node/wiki/Installation)
29 2. npm (Node package manager) - [https://github.com/isaacs/npm](https://github.com/isaacs/npm)
30 3. Redis - [http://redis.io/download](http://redis.io/download)
31
32 INSTALLATION INSTRUCTIONS FOR I/O DOCS
33 --------------------------------------
34 From the command line type in:
35 <pre> git clone http://github.com/mashery/iodocs.git
36 cd iodocs
6ea7104 @precision typo
precision authored
37 npm install
d5bf45d @mansilladev Readme file added.
mansilladev authored
38 </pre>
39
0200742 @precision remove the bit about using npm to autoinstall, we're not published to
precision authored
40
d5bf45d @mansilladev Readme file added.
mansilladev authored
41 ### Node Module Dependencies
42 These will be automatically installed when you use any of the above *npm* installation methods above.
43
6ae466e @precision links were backwards
precision authored
44 1. [express](http://expressjs.com/) - framework
67fe959 @mansilladev Corrected link to the node OAuth library in use.
mansilladev authored
45 2. [oauth](https://github.com/ciaranj/node-oauth) - oauth library
6ae466e @precision links were backwards
precision authored
46 3. [redis](https://github.com/mranney/node_redis) - connector to Redis
47 3. [connect-redis](https://github.com/visionmedia/connect-redis) - Redis session store
d8f5732 @mansilladev Extended signature+digest; package.json update
mansilladev authored
48 4. [querystring](https://github.com/visionmedia/node-querystring) - used to parse query string
49 5. [jade](http://jade-lang.com/) - the view engine
50
51 Note: hashlib is no longer a required module -- we're using the internal crypto module for signatures and digests.
d5bf45d @mansilladev Readme file added.
mansilladev authored
52
53 RUNNING I/O DOCS
54 ----------------
55 1. You will need to copy *config.json.sample* to *config.json*. The defaults will work, but feel free to change them.
56 2. node ./app.js
57 3. Point your browser to: [http://localhost:3000](http://localhost:3000)
58
59 QUICK API CONFIGURATION EXAMPLE
60 -------------------------------
61 Adding an API to the I/O Docs configuration is relatively simple.
62
04d86bc @kmiyashiro Remove line numbers, balancing braces, syntax highlighting.
kmiyashiro authored
63 First, append the new top-level service information to the `./public/data/apiconfig.json` file.
64
65 Example:
66
67 ```js
68 "lowercaseapi": {
69 "name": "Lower Case API",
70 "protocol": "http",
71 "baseURL": "api.lowercase.sample.com",
72 "publicPath": "/v1",
73 "auth": "key",
74 "keyParam": "api_key_var_name"
75 }
76 ```
77
78 Add the file `./public/data/lowercaseapi.json` to define the API.
79
80 Example:
81
82 ```js
83 {
84 "endpoints": [
d5bf45d @mansilladev Readme file added.
mansilladev authored
85 {
04d86bc @kmiyashiro Remove line numbers, balancing braces, syntax highlighting.
kmiyashiro authored
86 "name": "Resource Group A",
87 "methods": [
88 {
89 "MethodName": "Method A1",
90 "Synopsis": "Grabs information from the A1 data set",
91 "HTTPMethod": "GET",
92 "URI": "/a1/grab",
93 "RequiresOAuth": "N",
94 "parameters": [
95 {
96 "Name": "param_1_name",
97 "Required": "Y",
98 "Default": "",
99 "Type": "string",
100 "Description": "Description of the first parameter."
101 }
102 ]
103 }
104 ]
d5bf45d @mansilladev Readme file added.
mansilladev authored
105 }
04d86bc @kmiyashiro Remove line numbers, balancing braces, syntax highlighting.
kmiyashiro authored
106 ]
107 }
108 ```
d5bf45d @mansilladev Readme file added.
mansilladev authored
109
110 TOP-LEVEL SERVICE CONFIG DETAILS - apiconfig.json
111 -------------------------------------------------
112 The *apiconfig.json* file contains high-level information about an API.
113
114 ### Example #1 - Explanation of each field in an example API config that uses basic key authentication:
115
04d86bc @kmiyashiro Remove line numbers, balancing braces, syntax highlighting.
kmiyashiro authored
116 ```js
117 "lower": {
118 "name": "My API",
119 "protocol": "http",
120 "baseURL": "api.lowercase.sample.com",
121 "publicPath": "/v1",
122 "auth": "key",
123 "keyParam": "api_key_var_name"
124 }
125 ```
d5bf45d @mansilladev Readme file added.
mansilladev authored
126
127 Line:
128
129 1. Handle of the API. It is used to pull up the client
130 interface in the URL:
131
132 Ex: http://127.0.0.1:3000/lower
133
134 2. "name" key value is a string that holds the name
135 of the API that is used in the Jade template output.
136
36cfca2 @kamalgill Clarify protocol, baseURL, and publicPath config documentation
kamalgill authored
137 3. "protocol" key value is either *http* or *https*
d5bf45d @mansilladev Readme file added.
mansilladev authored
138
36cfca2 @kamalgill Clarify protocol, baseURL, and publicPath config documentation
kamalgill authored
139 4. "baseURL" key value is the host name of
140 the API calls (should not include protocol)
141
142 5. "publicPath" key value is the full path prefix prepended
143 to all method URIs. This value often includes the version
d5bf45d @mansilladev Readme file added.
mansilladev authored
144 in RESTful APIs.
145
36cfca2 @kamalgill Clarify protocol, baseURL, and publicPath config documentation
kamalgill authored
146 Ex: "/v1"
d5bf45d @mansilladev Readme file added.
mansilladev authored
147
d8f5732 @mansilladev Extended signature+digest; package.json update
mansilladev authored
148 In the Example #3 below, there is also "privatePath"
d5bf45d @mansilladev Readme file added.
mansilladev authored
149 which is used for endpoints behind protected resources.
150
36cfca2 @kamalgill Clarify protocol, baseURL, and publicPath config documentation
kamalgill authored
151 6. "auth" key value is the auth method. Valid values can be:
d5bf45d @mansilladev Readme file added.
mansilladev authored
152
153 "key" - simple API key in the URI
154 "oauth1" - OAuth 1.0/1.0a
36cfca2 @kamalgill Clarify protocol, baseURL, and publicPath config documentation
kamalgill authored
155 "" - no authentication
d5bf45d @mansilladev Readme file added.
mansilladev authored
156
36cfca2 @kamalgill Clarify protocol, baseURL, and publicPath config documentation
kamalgill authored
157 7. "keyParam" key value is name of the query parameter that
d5bf45d @mansilladev Readme file added.
mansilladev authored
158 is added to an API request when the "auth" key value from
159 (5) is set to "key"
160
36cfca2 @kamalgill Clarify protocol, baseURL, and publicPath config documentation
kamalgill authored
161 8. Closing curly-bracket ;)
d5bf45d @mansilladev Readme file added.
mansilladev authored
162
163
164 ---
165
d8f5732 @mansilladev Extended signature+digest; package.json update
mansilladev authored
166 ### Example #2 - Explanation of each field in an example API config that uses basic key authentication with signatures (signed call).
167
168 ```js
169 "upper": {
170 "name": "Upper API",
171 "protocol": "http",
172 "baseURL": "api.upper.sample.com",
173 "publicPath": "/v3",
174 "auth": "key",
175 "keyParam": "api_key_var_name",
176 "signature": {
177 "type": "signed_md5",
178 "sigParam": "sig",
179 "digest": "hex"
180 }
181 }
182 ```
183
184 Line:
185
186 1. Handle of the API. It is used to pull up the client
187 interface in the URL:
188
189 Ex: http://127.0.0.1:3000/upper
190
191 2. "name" key value is a string that holds the name
192 of the API that is used in the Jade template output.
193
194 3. "protocol" key value is either *http* or *https*
195
196 4. "baseURL" key value is the host name of
197 the API calls (should not include protocol)
198
199 5. "publicPath" key value is the full path prefix prepended
200 to all method URIs. This value often includes the version
201 in RESTful APIs.
202
203 Ex: "/v3"
204
205 In the Example #3 below, there is also "privatePath"
206 which is used for endpoints behind protected resources.
207
208 6. "auth" key value is the auth method. Valid values can be:
209
210 "key" - simple API key in the URI
211 "oauth1" - OAuth 1.0/1.0a
212 "" - no authentication
213
214 7. "keyParam" key value is the name of the query parameter that
215 is added to an API request when the "auth" key value from
216 (5) is set to "key"
217
218 8. "signature" is a JSON object that contains the details about
219 the API call signing requirements. The signature routine coded
220 in app.js is a hash of the string concatenation of API key,
221 API key secret and timestamp (epoch).
222
223 9. "type" key value is either *signed_md5* or *signed_sha256*.
224 More signature methods are available with crypto.js, but have
225 not been included in the code as options.
226
227 10. "sigParam" key value is the name of the query parameter that
228 is added to an API request that holds the digital signature.
229
230 11. "digest" key value is the digest algorithm that is used.
231 Values can be *hex*, *base64* or *binary*.
232
233 12. Closing curly-bracket for the "signature" object
234
235 13. Closing curly bracket for main object.
236
237
238 ---
239
240
241 ### Example #3 - Twitter API config that uses 3-legged OAuth
d5bf45d @mansilladev Readme file added.
mansilladev authored
242
04d86bc @kmiyashiro Remove line numbers, balancing braces, syntax highlighting.
kmiyashiro authored
243 ```js
244 "twitter": {
245 "name": "Twitter API",
246 "protocol": "http",
247 "baseURL": "api.twitter.com",
248 "publicPath": "/1",
249 "privatePath": "/1",
250 "booleanTrueVal": "true",
251 "booleanFalseVal": "false",
252 "auth": "oauth",
253 "oauth" : {
254 "type": "three-legged",
255 "requestURL": "https://api.twitter.com/oauth/request_token",
256 "signinURL": "https://api.twitter.com/oauth/authorize?oauth_token="
257 "accessURL": "https://api.twitter.com/oauth/access_token",
258 "version": "1.0",
259 "crypt": "HMAC-SHA1",
260 }
261 "keyParam": "",
262 }
263 ```
d5bf45d @mansilladev Readme file added.
mansilladev authored
264
265 Line:
266
267 1. Handle of the API. It is used to pull up the client
268 interface in the URL:
269
5625296 @mansilladev OAuth related fixes
mansilladev authored
270 Ex: http://127.0.0.1:3000/twitter
d5bf45d @mansilladev Readme file added.
mansilladev authored
271
272 2. "name" key value is a string that holds the name
273 of the API that is used in the Jade template output.
274
0d57c0c @mansilladev Updated README with "protocol" parameter
mansilladev authored
275 3. "protocol" key value contains either *http* or *https*,
276 but you're welcome to try other protocols.
277
278 4. "baseURL" key value is the base URL that accepts
36cfca2 @kamalgill Clarify protocol, baseURL, and publicPath config documentation
kamalgill authored
279 the API calls (should not include protocol)
d5bf45d @mansilladev Readme file added.
mansilladev authored
280
0d57c0c @mansilladev Updated README with "protocol" parameter
mansilladev authored
281 5. "publicPath" key value is the path prefix prepended
d5bf45d @mansilladev Readme file added.
mansilladev authored
282 to all method URIs for non-protected method resources.
36cfca2 @kamalgill Clarify protocol, baseURL, and publicPath config documentation
kamalgill authored
283 This value often includes the version in RESTful APIs.
d5bf45d @mansilladev Readme file added.
mansilladev authored
284
285 Ex: "/v1", "/1", etc.
286
0d57c0c @mansilladev Updated README with "protocol" parameter
mansilladev authored
287 6. "privatePath" key value is the path prefix prepended
d5bf45d @mansilladev Readme file added.
mansilladev authored
288 to all method URIs for OAuth protected method resources.
289 This value is most often the version in RESTful APIs.
290
291 Ex: "/v1", "/1", etc.
292
0d57c0c @mansilladev Updated README with "protocol" parameter
mansilladev authored
293 7. "booleanTrueVal" key value is the default value for
d5bf45d @mansilladev Readme file added.
mansilladev authored
294 true Boolean values that are sent in API requests.
295 Some APIs are designed to accept a wide variety
296 of true derivatives, but some are very strict about
297 this value.
298
299 Ex: "true", "TRUE", "True", "t", "T", "1", etc.
300 Default: "true"
301
0d57c0c @mansilladev Updated README with "protocol" parameter
mansilladev authored
302 8. "booleanFalseVal" key value is the default value for
d5bf45d @mansilladev Readme file added.
mansilladev authored
303 false Boolean values that are sent in API requests.
304 Some APIs are designed to accept a wide variety
305 of false derivatives, but some are very strict about
306 this value.
307
308 Ex: "false", "FALSE", "False", "f", "F", "0", etc.
309 Default: "false"
310
0d57c0c @mansilladev Updated README with "protocol" parameter
mansilladev authored
311 9. "auth" key value is set to "oauth" when OAuth is the
d5bf45d @mansilladev Readme file added.
mansilladev authored
312 authentication mechanism. Field is required.
313
0d57c0c @mansilladev Updated README with "protocol" parameter
mansilladev authored
314 10. "oauth" key value is a JSON object that contains the
d5bf45d @mansilladev Readme file added.
mansilladev authored
315 OAuth implementation details for this API. Field is
316 required when "auth" value is "oauth".
317
0d57c0c @mansilladev Updated README with "protocol" parameter
mansilladev authored
318 11. "type" key value is the OAuth is the authorization flow
5625296 @mansilladev OAuth related fixes
mansilladev authored
319 used for this API. Valid values are "three-legged" (normal
320 authorization flow) and "two-legged" (no authorization flow).
d5bf45d @mansilladev Readme file added.
mansilladev authored
321
0d57c0c @mansilladev Updated README with "protocol" parameter
mansilladev authored
322 12. "requestURL" key value is the Request Token URL used in
5625296 @mansilladev OAuth related fixes
mansilladev authored
323 the OAuth dance (used in *three-legged* scenario).
d5bf45d @mansilladev Readme file added.
mansilladev authored
324
0d57c0c @mansilladev Updated README with "protocol" parameter
mansilladev authored
325 13. "signinURL" key value is the User Authorization URL used
d5bf45d @mansilladev Readme file added.
mansilladev authored
326 in the OAuth dance (where the user is redirected to provide
5625296 @mansilladev OAuth related fixes
mansilladev authored
327 their credentials -- used in *three-legged* scenario).
d5bf45d @mansilladev Readme file added.
mansilladev authored
328
0d57c0c @mansilladev Updated README with "protocol" parameter
mansilladev authored
329 14. "accessURL" key value is the Access Token URL used in the
5625296 @mansilladev OAuth related fixes
mansilladev authored
330 OAuth dance (used in *three-legged* scenario).
d5bf45d @mansilladev Readme file added.
mansilladev authored
331
0d57c0c @mansilladev Updated README with "protocol" parameter
mansilladev authored
332 15. "version" key value is the OAuth version. As of I/O Docs v1.1,
d5bf45d @mansilladev Readme file added.
mansilladev authored
333 "1.0" is the only supported version. Note: use "1.0" for both
334 1.0 and 1.0A implementations.
335
0d57c0c @mansilladev Updated README with "protocol" parameter
mansilladev authored
336 16. "crypt" key value is the OAuth signature method. As of I/O Docs
d5bf45d @mansilladev Readme file added.
mansilladev authored
337 v1.1 "HMAC-SHA1" is the only supported signing method.
338
0d57c0c @mansilladev Updated README with "protocol" parameter
mansilladev authored
339 17. Closing curly bracket for "oauth" JSON object.
d5bf45d @mansilladev Readme file added.
mansilladev authored
340
0d57c0c @mansilladev Updated README with "protocol" parameter
mansilladev authored
341 18. "keyParam" key value is blank when OAuth is the authentication
d5bf45d @mansilladev Readme file added.
mansilladev authored
342 method.
343
0d57c0c @mansilladev Updated README with "protocol" parameter
mansilladev authored
344 19. Closing curly bracket for main object.
d5bf45d @mansilladev Readme file added.
mansilladev authored
345
346
347 API-LEVEL CONFIG DETAILS
348 ========================
349 For every API that is configured in *apiconfig.json* a JSON config file must exist.
350 You should look at the *./public/data/* directory for examples.
351
352 ### Example #1 - Explanation of each field in an example API-level configuration
353
04d86bc @kmiyashiro Remove line numbers, balancing braces, syntax highlighting.
kmiyashiro authored
354 ```js
355 {
356 "name":"User Resources",
357 "methods":[
358 {
359 "MethodName":"users/show",
360 "Synopsis":"Returns extended user information",
361 "HTTPMethod":"GET",
362 "URI":"/users/show.json",
363 "RequiresOAuth":"N",
364 "parameters":[
365 {
366 "Name":"user_id",
367 "Required":"Y",
368 "Default":"",
369 "Type":"string",
370 "Description":"The ID of the user",
371 },
372 {
373 "Name":"cereal",
374 "Required":"Y",
375 "Default":"fruitscoops",
376 "Type":"enumerated",
377 "EnumeratedList": [
378 "fruitscoops",
379 "sugarbombs",
380 "frostedteeth"
381 ],
2f7b489 @martintajur support for EnumeratedDescription to better describe enumerated prope…
martintajur authored
382 "EnumeratedDescription": {
383 "fruitscoops": "Fruit Scoops (packed with fruit goodness)",
384 "sugarbombs": "Sugar Bombs (filled with sugar)",
385 "frostedteeth": "Frosted Teeth (sugar coating)"
386 },
04d86bc @kmiyashiro Remove line numbers, balancing braces, syntax highlighting.
kmiyashiro authored
387 "Description":"The type of cereal desired"
388 },
389 {
390 "Name":"skip_status",
391 "Required":"N",
392 "Default":"",
393 "Type":"boolean",
394 "Description":"If true, status not included"
395 }
396 ]
397 }]
398 }
399 ```
d5bf45d @mansilladev Readme file added.
mansilladev authored
400
401 Line:
402
403 3. "name" key holds the value of the Resource name. Methods are grouped into Resources.
404
405 4. "methods" key value is an array of JSON objects (each one being a method)
406
407 6. "MethodName" key value is a string that is displayed via the view template.
408
409 7. "Synopsis" key value is a short description of the method.
410
411 8. "HTTPMethod" key value can be either GET, POST, DELETE or PUT (all caps)
412
413 9. "URI" key value is the path to the method that is appended to the *baseURL* and the public/private path.
414
415 10. "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.
416
417 11. "parameters" key value is an array of JSON objects (each one being a parameter)
418
419 13. "Name" key value is a string that contains the name of the parameter.
420
421 14. "Required" key value is either Y or N. If Y, the parameter will be output as bold.
422
423 15. "Default" key value is a string, containing a default value that will be automatically populated onto the form.
424
425 16. "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.
426
427 17. "Description" key value is a string, containing the description of the parameter.
428
429 23. "Type" key value is set to *enumerated* for this parameter.
430
431 24. "EnumeratedList" key value is an array of enumerated values that will render a drop-down (select box) on the form.
432
2f7b489 @martintajur support for EnumeratedDescription to better describe enumerated prope…
martintajur authored
433 25. "EnumeratedDescription" key value is an object of enumerated values as keys, and their descriptions as values that will be displayed below the Description.
d5bf45d @mansilladev Readme file added.
mansilladev authored
434
2f7b489 @martintajur support for EnumeratedDescription to better describe enumerated prope…
martintajur authored
435 26. Each value in the list is a string.
436
437 27. "Type" key value is *boolean* that will render a drop-down (select box) on the form for *true* and *false*.
d5bf45d @mansilladev Readme file added.
mansilladev authored
438
439 SUPPORT
440 =======
9d399d8 @precision point users directly to the github issues page
precision authored
441 If you need any help with I/O Docs, you can reach out to us via the GitHub Issues page at:
442 <code>[http://github.com/mashery/iodocs/issues](http://github.com/mashery/iodocs/issues)</code>
Something went wrong with that request. Please try again.