Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 666 lines (518 sloc) 24.291 kb
f4507f3 @mansilladev More schema updates (auth.oauth.token.*) for location and param name; ad...
mansilladev authored
1 I/O Docs Community Edition in Node.js
2 =====================================
3 Copyright 2011-2014 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
38150f8 @mansilladev Major changes logged to README
mansilladev authored
9 MAJOR CHANGE LOG
10 ================
11 ### 2014-07-22 - Summer Release Feature Enhancements
12 #### 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.
13
14 * Numerous schema changes and improvements
15 * Support for references
16 * Base paths and authorization moved from apiConfig to api{name}.json files
17 * More robust/extensible auth definition block
18 * POST/PUT request body capabilities added
19 * Array type and interface added for use in request body
20 * Size and order support
21 * Serialized JSON support
22 * Parameter location enhancements
23 * Placement in the query string, path or header
24 * Method form UI generation driven by Alpaca/jQuery
25
d5bf45d @mansilladev Readme file added.
mansilladev authored
26 SYNOPSIS
27 --------
f4507f3 @mansilladev More schema updates (auth.oauth.token.*) for location and param name; ad...
mansilladev authored
28 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.
d5bf45d @mansilladev Readme file added.
mansilladev authored
29
30 You can find the latest version here: [https://github.com/mashery/iodocs](https://github.com/mashery/iodocs)
31
32 However, we recommend that you install I/O Docs with *npm*, the Node package manager. See instructions below.
33
34 BUILD/RUNTIME DEPENDENCIES
35 --------------------------
36 1. Node.js - server-side JS engine
37 2. npm - node package manager
73551d0 @mansilladev Update README
mansilladev authored
38 3. Redis - key+value storage engine
d5bf45d @mansilladev Readme file added.
mansilladev authored
39
73551d0 @mansilladev Update README
mansilladev authored
40 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.
41
42 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.
d5bf45d @mansilladev Readme file added.
mansilladev authored
43
44 INSTALLATION INSTRUCTIONS FOR NODE, NPM & REDIS
45 -----------------------------------------------
46 1. Node.js - [https://github.com/joyent/node/wiki/Installation](https://github.com/joyent/node/wiki/Installation)
47 2. npm (Node package manager) - [https://github.com/isaacs/npm](https://github.com/isaacs/npm)
48 3. Redis - [http://redis.io/download](http://redis.io/download)
49
50 INSTALLATION INSTRUCTIONS FOR I/O DOCS
51 --------------------------------------
52 From the command line type in:
53 <pre> git clone http://github.com/mashery/iodocs.git
54 cd iodocs
6ea7104 @precision typo
precision authored
55 npm install
d5bf45d @mansilladev Readme file added.
mansilladev authored
56 </pre>
57
0200742 @precision remove the bit about using npm to autoinstall, we're not published to
precision authored
58
d5bf45d @mansilladev Readme file added.
mansilladev authored
59 ### Node Module Dependencies
60 These will be automatically installed when you use any of the above *npm* installation methods above.
61
6ae466e @precision links were backwards
precision authored
62 1. [express](http://expressjs.com/) - framework
67fe959 @mansilladev Corrected link to the node OAuth library in use.
mansilladev authored
63 2. [oauth](https://github.com/ciaranj/node-oauth) - oauth library
6ae466e @precision links were backwards
precision authored
64 3. [redis](https://github.com/mranney/node_redis) - connector to Redis
636ad29 @alexadkins Edited README
alexadkins authored
65 4. [connect-redis](https://github.com/visionmedia/connect-redis) - Redis session store
66 5. [querystring](https://github.com/visionmedia/node-querystring) - used to parse query string
67 6. [jade](http://jade-lang.com/) - the view engine
68 7. [supervisor](https://github.com/isaacs/node-supervisor) - restart node upon an error or changed javascript file
d8f5732 @mansilladev Extended signature+digest; package.json update
mansilladev authored
69
70 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
71
72 RUNNING I/O DOCS
73 ----------------
0646dad @switzer Added supervisor to the package, and a script to start the app using npm...
switzer authored
74 **Create your config** file by copying the default config:
75
76 ```
77 cp config.json.sample config.json
78 ```
79 The defaults will work, but feel free to change them.
80
f04b397 @alexadkins Changed README
alexadkins authored
81 **Run a Redis instance:**
82
83 ```
84 redis-server
85 ```
86
0646dad @switzer Added supervisor to the package, and a script to start the app using npm...
switzer authored
87 **Start I/O Docs**:
88
89 ```
af3006f @silentdth Add ability to run npm start on Windows platform
silentdth authored
90 npm start (*nix, Mac OSX)
91 npm run-script startwin (Windows)
0646dad @switzer Added supervisor to the package, and a script to start the app using npm...
switzer authored
92 ```
93
2c1bac1 @rowanhill Allow config.json location to be configured by argument to app.js
rowanhill authored
94 **Start I/O Docs with a custom config file**:
95
96 ```
97 ./node_modules/.bin/supervisor -e 'js|json' -- app --config-file ../config.json (*nix, Mac OSX)
98 supervisor -e 'js' -- app --config-file ../config.json (Windows)
99 ```
100
101 Ideally, the `--config-file` arg would be possible to use with `npm start`, but until
102 [npm issue #3494](https://github.com/isaacs/npm/issues/3494) is resolved, this is not supported.
af3006f @silentdth Add ability to run npm start on Windows platform
silentdth authored
103
0646dad @switzer Added supervisor to the package, and a script to start the app using npm...
switzer authored
104 **Point your browser** to: [localhost:3000](http://localhost:3000)
d5bf45d @mansilladev Readme file added.
mansilladev authored
105
1b1878b @rowanhill Allow API definition dir to be configured in config.json
rowanhill authored
106 CONFIGURING API DEFINITION LOCATION
107 -----------------------------------
8ff62fc @alexadkins Schema changes, request body capabilities, array types, & location enhan...
alexadkins authored
108 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
1b1878b @rowanhill Allow API definition dir to be configured in config.json
rowanhill authored
109 be overridden in `config.json` by setting the `"apiConfigDir"` property.
110
7f3df0a @mansilladev Add support for server-side basic auth
mansilladev authored
111
112 BASIC AUTH FOR SERVER
113 ---------------------
114 Enabling HTTP basic authentication on the server is simple. By default, the username and password values are empty ("").
115
116 1. Open up *config.json*
117 2. Navigate down to the *basicAuth* object
118 3. Add values for username and password within the object
119
120
d5bf45d @mansilladev Readme file added.
mansilladev authored
121 QUICK API CONFIGURATION EXAMPLE
122 -------------------------------
123 Adding an API to the I/O Docs configuration is relatively simple.
124
8ff62fc @alexadkins Schema changes, request body capabilities, array types, & location enhan...
alexadkins authored
125 First, append the api name to the `./public/data/apiconfig.json` file.
04d86bc @kmiyashiro Remove line numbers, balancing braces, syntax highlighting.
kmiyashiro authored
126
127 Example:
128
129 ```js
130 "lowercaseapi": {
8ff62fc @alexadkins Schema changes, request body capabilities, array types, & location enhan...
alexadkins authored
131 "name": "Lower Case API"
04d86bc @kmiyashiro Remove line numbers, balancing braces, syntax highlighting.
kmiyashiro authored
132 }
133 ```
134
8ff62fc @alexadkins Schema changes, request body capabilities, array types, & location enhan...
alexadkins authored
135 Add the file `./public/data/lowercaseapi.json` to define the API.
04d86bc @kmiyashiro Remove line numbers, balancing braces, syntax highlighting.
kmiyashiro authored
136
137 Example:
138
139 ```js
8ff62fc @alexadkins Schema changes, request body capabilities, array types, & location enhan...
alexadkins authored
140
04d86bc @kmiyashiro Remove line numbers, balancing braces, syntax highlighting.
kmiyashiro authored
141 {
8ff62fc @alexadkins Schema changes, request body capabilities, array types, & location enhan...
alexadkins authored
142 "name": "Lower Case API",
143 "description": "An example api.",
144 "protocol": "rest",
145 "basePath": "http://api.lowercase.sample.com",
146 "publicPath": "/v1",
147 "auth": {
148 "key": {
149 "param": "key"
150 }
151 },
152 "headers": {
153 "Accept": "application/json",
154 "Foo": "bar"
155 },
156 "resources": {
157 "Resource Group A": {
158 "methods": {
159 "MethodA1": {
160 "name": "Method A1",
161 "path": "/a1/grab",
162 "httpMethod": "GET",
163 "description": "Grabs information from the A1 data set.",
164 "parameters": {
165 "param1": {
166 "type": "string",
167 "required": true,
168 "default": "",
169 "description": "Description of the first parameter."
04d86bc @kmiyashiro Remove line numbers, balancing braces, syntax highlighting.
kmiyashiro authored
170 }
8ff62fc @alexadkins Schema changes, request body capabilities, array types, & location enhan...
alexadkins authored
171 }
888c68b Update documentation to answer questions from issue #112 & issue #118
Mike Tougeron authored
172 },
8ff62fc @alexadkins Schema changes, request body capabilities, array types, & location enhan...
alexadkins authored
173 "MethodA1User": {
174 "name": "Method A1 User",
175 "path": "/a1/grab/{userId}",
176 "httpMethod": "GET",
177 "description": "Grabs information from the A1 data set for a specific user",
178 "parameters": {
179 "param1": {
180 "type": "string",
181 "required": true,
182 "default": "",
183 "description": "Description of the first parameter."
888c68b Update documentation to answer questions from issue #112 & issue #118
Mike Tougeron authored
184 },
8ff62fc @alexadkins Schema changes, request body capabilities, array types, & location enhan...
alexadkins authored
185 "userId": {
186 "type": "string",
187 "required": true,
188 "default": "",
189 "description": "The userId parameter that is in the URI."
888c68b Update documentation to answer questions from issue #112 & issue #118
Mike Tougeron authored
190 }
8ff62fc @alexadkins Schema changes, request body capabilities, array types, & location enhan...
alexadkins authored
191 }
04d86bc @kmiyashiro Remove line numbers, balancing braces, syntax highlighting.
kmiyashiro authored
192 }
8ff62fc @alexadkins Schema changes, request body capabilities, array types, & location enhan...
alexadkins authored
193 }
d5bf45d @mansilladev Readme file added.
mansilladev authored
194 }
8ff62fc @alexadkins Schema changes, request body capabilities, array types, & location enhan...
alexadkins authored
195 }
04d86bc @kmiyashiro Remove line numbers, balancing braces, syntax highlighting.
kmiyashiro authored
196 }
197 ```
d5bf45d @mansilladev Readme file added.
mansilladev authored
198
888c68b Update documentation to answer questions from issue #112 & issue #118
Mike Tougeron authored
199 By default the parameters are added to the query string. But if the URI contains a named variable, it will substitute the value in the path.
200
8ff62fc @alexadkins Schema changes, request body capabilities, array types, & location enhan...
alexadkins authored
201 TOP-LEVEL SERVICE CONFIG DETAILS
d5bf45d @mansilladev Readme file added.
mansilladev authored
202 -------------------------------------------------
8ff62fc @alexadkins Schema changes, request body capabilities, array types, & location enhan...
alexadkins authored
203
204 The *apiconfig.json* file contains the name of an API to show upon initiation.
205
206 ```js
207 "lowercaseapi": {
208 "name": "Lower Case API"
209 }
210 ```
211
212 The high-level information about an API is set in the config JSON file.
d5bf45d @mansilladev Readme file added.
mansilladev authored
213
214 ### Example #1 - Explanation of each field in an example API config that uses basic key authentication:
215
04d86bc @kmiyashiro Remove line numbers, balancing braces, syntax highlighting.
kmiyashiro authored
216 ```js
8ff62fc @alexadkins Schema changes, request body capabilities, array types, & location enhan...
alexadkins authored
217 {
218 "name": "Lower Case API",
219 "protocol": "rest",
220 "basePath": "http://api.lowercase.sample.com",
a077c96 @mansilladev Added headers example
mansilladev authored
221 "publicPath": "/v1",
8ff62fc @alexadkins Schema changes, request body capabilities, array types, & location enhan...
alexadkins authored
222 "auth": {
223 "key": {
224 "param": "key",
225 "location": "query"
226 }
227 },
a077c96 @mansilladev Added headers example
mansilladev authored
228 "headers": {
8ff62fc @alexadkins Schema changes, request body capabilities, array types, & location enhan...
alexadkins authored
229 "Accept": "application/json",
230 "Foo": "bar"
231 },
232 ...
04d86bc @kmiyashiro Remove line numbers, balancing braces, syntax highlighting.
kmiyashiro authored
233 ```
d5bf45d @mansilladev Readme file added.
mansilladev authored
234
235 Line:
236
636ad29 @alexadkins Edited README
alexadkins authored
237 (1). "name" key value is a string that holds the name
8ff62fc @alexadkins Schema changes, request body capabilities, array types, & location enhan...
alexadkins authored
238 of the API that is used in the Jade template output. Also true in *apiconfig.json*.
d5bf45d @mansilladev Readme file added.
mansilladev authored
239
636ad29 @alexadkins Edited README
alexadkins authored
240 (2). "protocol" key value is either *rest* or *soap*
d5bf45d @mansilladev Readme file added.
mansilladev authored
241
636ad29 @alexadkins Edited README
alexadkins authored
242 (3). "basePath" key value is the host path of
8ff62fc @alexadkins Schema changes, request body capabilities, array types, & location enhan...
alexadkins authored
243 the API calls
d5bf45d @mansilladev Readme file added.
mansilladev authored
244
636ad29 @alexadkins Edited README
alexadkins authored
245 (4). "publicPath" key value is the full path prefix prepended
36cfca2 @kamalgill Clarify protocol, baseURL, and publicPath config documentation
kamalgill authored
246 to all method URIs. This value often includes the version
d5bf45d @mansilladev Readme file added.
mansilladev authored
247 in RESTful APIs.
248
36cfca2 @kamalgill Clarify protocol, baseURL, and publicPath config documentation
kamalgill authored
249 Ex: "/v1"
d5bf45d @mansilladev Readme file added.
mansilladev authored
250
d8f5732 @mansilladev Extended signature+digest; package.json update
mansilladev authored
251 In the Example #3 below, there is also "privatePath"
d5bf45d @mansilladev Readme file added.
mansilladev authored
252 which is used for endpoints behind protected resources.
253
636ad29 @alexadkins Edited README
alexadkins authored
254 (5). "auth" container holds the authorization information. If absent, API requires no authorization.
d5bf45d @mansilladev Readme file added.
mansilladev authored
255
636ad29 @alexadkins Edited README
alexadkins authored
256 (6). The key value that describes the auth method. Valid values can be:
d5bf45d @mansilladev Readme file added.
mansilladev authored
257 "key" - simple API key in the URI
8ff62fc @alexadkins Schema changes, request body capabilities, array types, & location enhan...
alexadkins authored
258 "oauth" - OAuth 1.0/2.0
36cfca2 @kamalgill Clarify protocol, baseURL, and publicPath config documentation
kamalgill authored
259 "" - no authentication
d5bf45d @mansilladev Readme file added.
mansilladev authored
260
636ad29 @alexadkins Edited README
alexadkins authored
261 (7). "param" key value is name of the parameter that
d5bf45d @mansilladev Readme file added.
mansilladev authored
262 is added to an API request when the "auth" key value from
8ff62fc @alexadkins Schema changes, request body capabilities, array types, & location enhan...
alexadkins authored
263 (6) is set to "key".
a077c96 @mansilladev Added headers example
mansilladev authored
264
636ad29 @alexadkins Edited README
alexadkins authored
265 (8). "location" (optional) key value sets where the api key will go in the request. Defaults to "query".
0b7e60f Update readme
Rai Phairow authored
266 supported values: "query" and "header".
8ff62fc @alexadkins Schema changes, request body capabilities, array types, & location enhan...
alexadkins authored
267
636ad29 @alexadkins Edited README
alexadkins authored
268 (9). "headers" object contains key value pairs of HTTP headers
a077c96 @mansilladev Added headers example
mansilladev authored
269 that will be sent for each request for API. These are
270 static key/value pairs.
d5bf45d @mansilladev Readme file added.
mansilladev authored
271
272 ---
273
d8f5732 @mansilladev Extended signature+digest; package.json update
mansilladev authored
274 ### Example #2 - Explanation of each field in an example API config that uses basic key authentication with signatures (signed call).
275
276 ```js
8ff62fc @alexadkins Schema changes, request body capabilities, array types, & location enhan...
alexadkins authored
277 {
278 "name": "Lower Case API",
279 "protocol": "rest",
280 "basePath": "http://api.lowercase.sample.com",
281 "publicPath": "/v1",
282 "auth": {
283 "key": {
284 "param": "key",
285 "signature": {
286 "type": "signed_md5",
287 "param": "sig",
288 "digest": "hex",
289 "location": "header"
290 }
291 }
292 },
293 ...
d8f5732 @mansilladev Extended signature+digest; package.json update
mansilladev authored
294 ```
295
296 Line:
297
636ad29 @alexadkins Edited README
alexadkins authored
298 (1). "name" key value is a string that holds the name
8ff62fc @alexadkins Schema changes, request body capabilities, array types, & location enhan...
alexadkins authored
299 of the API that is used in the Jade template output. Also true in *apiconfig.json*.
d8f5732 @mansilladev Extended signature+digest; package.json update
mansilladev authored
300
636ad29 @alexadkins Edited README
alexadkins authored
301 (2). "protocol" key value is either *rest* or *soap*
d8f5732 @mansilladev Extended signature+digest; package.json update
mansilladev authored
302
636ad29 @alexadkins Edited README
alexadkins authored
303 (3). "basePath" key value is the host path of
8ff62fc @alexadkins Schema changes, request body capabilities, array types, & location enhan...
alexadkins authored
304 the API calls
d8f5732 @mansilladev Extended signature+digest; package.json update
mansilladev authored
305
636ad29 @alexadkins Edited README
alexadkins authored
306 (4). "publicPath" key value is the full path prefix prepended
d8f5732 @mansilladev Extended signature+digest; package.json update
mansilladev authored
307 to all method URIs. This value often includes the version
308 in RESTful APIs.
309
8ff62fc @alexadkins Schema changes, request body capabilities, array types, & location enhan...
alexadkins authored
310 Ex: "/v1"
d8f5732 @mansilladev Extended signature+digest; package.json update
mansilladev authored
311
312 In the Example #3 below, there is also "privatePath"
313 which is used for endpoints behind protected resources.
314
636ad29 @alexadkins Edited README
alexadkins authored
315 (5). "auth" container holds the authorization information. If absent, API requires no authorization.
d8f5732 @mansilladev Extended signature+digest; package.json update
mansilladev authored
316
636ad29 @alexadkins Edited README
alexadkins authored
317 (6). The key value that describes the auth method. Valid values can be:
d8f5732 @mansilladev Extended signature+digest; package.json update
mansilladev authored
318 "key" - simple API key in the URI
8ff62fc @alexadkins Schema changes, request body capabilities, array types, & location enhan...
alexadkins authored
319 "oauth" - OAuth 1.0/2.0
d8f5732 @mansilladev Extended signature+digest; package.json update
mansilladev authored
320
636ad29 @alexadkins Edited README
alexadkins authored
321 (7). "param" key value is name of the parameter that
d8f5732 @mansilladev Extended signature+digest; package.json update
mansilladev authored
322 is added to an API request when the "auth" key value from
8ff62fc @alexadkins Schema changes, request body capabilities, array types, & location enhan...
alexadkins authored
323 (6) is set to "key".
d8f5732 @mansilladev Extended signature+digest; package.json update
mansilladev authored
324
636ad29 @alexadkins Edited README
alexadkins authored
325 (8). "signature" is a JSON object that contains the details about
d8f5732 @mansilladev Extended signature+digest; package.json update
mansilladev authored
326 the API call signing requirements. The signature routine coded
327 in app.js is a hash of the string concatenation of API key,
328 API key secret and timestamp (epoch).
329
636ad29 @alexadkins Edited README
alexadkins authored
330 (9). "type" key value is either *signed_md5* or *signed_sha256*.
d8f5732 @mansilladev Extended signature+digest; package.json update
mansilladev authored
331 More signature methods are available with crypto.js, but have
332 not been included in the code as options.
333
636ad29 @alexadkins Edited README
alexadkins authored
334 (10). "param" key value is the name of the parameter that
d8f5732 @mansilladev Extended signature+digest; package.json update
mansilladev authored
335 is added to an API request that holds the digital signature.
336
636ad29 @alexadkins Edited README
alexadkins authored
337 (11). "digest" key value is the digest algorithm that is used.
d8f5732 @mansilladev Extended signature+digest; package.json update
mansilladev authored
338 Values can be *hex*, *base64* or *binary*.
339
636ad29 @alexadkins Edited README
alexadkins authored
340 (12). "location" (optional) key value sets where the signature will go in the request. Defaults to "header".
d5bf45d @mansilladev Readme file added.
mansilladev authored
341
342
5be5ffc @alexadkins OAuth2 documentation in README
alexadkins authored
343 ---
344
345
8ff62fc @alexadkins Schema changes, request body capabilities, array types, & location enhan...
alexadkins authored
346 ### Example #3 - Foursquare API config that uses 3-legged OAuth 2.0
5be5ffc @alexadkins OAuth2 documentation in README
alexadkins authored
347
348 ```js
8ff62fc @alexadkins Schema changes, request body capabilities, array types, & location enhan...
alexadkins authored
349 {
5be5ffc @alexadkins OAuth2 documentation in README
alexadkins authored
350 "name": "Foursquare (OAuth 2.0 Auth Code)",
8ff62fc @alexadkins Schema changes, request body capabilities, array types, & location enhan...
alexadkins authored
351 "protocol": "rest",
352 "basePath": "https://api.foursquare.com",
5be5ffc @alexadkins OAuth2 documentation in README
alexadkins authored
353 "privatePath": "/v2",
8ff62fc @alexadkins Schema changes, request body capabilities, array types, & location enhan...
alexadkins authored
354 "auth": {
355 "oauth": {
356 "version": "2.0",
357 "type": "authorization-code",
358 "base_uri": "https://foursquare.com/",
359 "authorize_uri": "oauth2/authenticate",
496de1d @matehat Fix unterminated string literal
matehat authored
360 "access_token_uri": "oauth2/access_token_uri",
f4507f3 @mansilladev More schema updates (auth.oauth.token.*) for location and param name; ad...
mansilladev authored
361 "token": {
362 "param": "oauth_token",
363 "location": "query"
364 }
8ff62fc @alexadkins Schema changes, request body capabilities, array types, & location enhan...
alexadkins authored
365 }
5be5ffc @alexadkins OAuth2 documentation in README
alexadkins authored
366 },
8ff62fc @alexadkins Schema changes, request body capabilities, array types, & location enhan...
alexadkins authored
367 ...
5be5ffc @alexadkins OAuth2 documentation in README
alexadkins authored
368 ```
369
370 Line:
371
8ff62fc @alexadkins Schema changes, request body capabilities, array types, & location enhan...
alexadkins authored
372 1. "name" key value is a string that holds the name
373 of the API that is used in the Jade template output. Also true in *apiconfig.json*.
5be5ffc @alexadkins OAuth2 documentation in README
alexadkins authored
374
8ff62fc @alexadkins Schema changes, request body capabilities, array types, & location enhan...
alexadkins authored
375 2. "protocol" key value is either *rest* or *soap*
5be5ffc @alexadkins OAuth2 documentation in README
alexadkins authored
376
8ff62fc @alexadkins Schema changes, request body capabilities, array types, & location enhan...
alexadkins authored
377 3. "basePath" key value is the host path of
378 the API calls
5be5ffc @alexadkins OAuth2 documentation in README
alexadkins authored
379
8ff62fc @alexadkins Schema changes, request body capabilities, array types, & location enhan...
alexadkins authored
380 4. "privatePath" key value is the path prefix prepended
381 to all method URIs for OAuth protected method resources.
5be5ffc @alexadkins OAuth2 documentation in README
alexadkins authored
382 This value is most often the version in RESTful APIs.
383
384 Ex: "/v1", "/1", etc.
385
8ff62fc @alexadkins Schema changes, request body capabilities, array types, & location enhan...
alexadkins authored
386 5. "auth" container holds the authorization information. If absent, API requires no authorization.
387
388 6. "oauth" key value is a JSON object that contains the
389 OAuth implementation details for this API.
5be5ffc @alexadkins OAuth2 documentation in README
alexadkins authored
390
8ff62fc @alexadkins Schema changes, request body capabilities, array types, & location enhan...
alexadkins authored
391 7. "version" key value is the OAuth version. OAuth 1.0 and 2.0 supported.
5be5ffc @alexadkins OAuth2 documentation in README
alexadkins authored
392
8ff62fc @alexadkins Schema changes, request body capabilities, array types, & location enhan...
alexadkins authored
393 8. "type" key value is the OAuth 2 authorization flow
5be5ffc @alexadkins OAuth2 documentation in README
alexadkins authored
394 used for this API. Valid values are "authorization-code",
395 "client_credentials", and "implicit", named for each grant
396 found here: "http://tools.ietf.org/html/rfc6749".
397
8ff62fc @alexadkins Schema changes, request body capabilities, array types, & location enhan...
alexadkins authored
398 9. "base_uri" key value is the base website URL used in
5be5ffc @alexadkins OAuth2 documentation in README
alexadkins authored
399 the OAuth 2 dance. It is required.
400
8ff62fc @alexadkins Schema changes, request body capabilities, array types, & location enhan...
alexadkins authored
401 10. "authorize_uri" key value is the url string used to
5be5ffc @alexadkins OAuth2 documentation in README
alexadkins authored
402 retrieve the authorization token in the
403 "authorization-code" OAuth 2 flow. This is not necessary
404 in any other OAuth 2 flow.
405
8ff62fc @alexadkins Schema changes, request body capabilities, array types, & location enhan...
alexadkins authored
406 11. "access_token_uri" key value is the url string used to
5be5ffc @alexadkins OAuth2 documentation in README
alexadkins authored
407 retrieve the access (Bearer) token in any OAuth 2 flow.
408 This is required in all OAuth 2 flows.
409
f4507f3 @mansilladev More schema updates (auth.oauth.token.*) for location and param name; ad...
mansilladev authored
410 12. "token" container instructs I/O Docs where to use the access/bearer token on requests. If the "location" is set
5be5ffc @alexadkins OAuth2 documentation in README
alexadkins authored
411 as the default token name when making calls with the
412 access token in the url query parameters. Not required if
413 "access_token" is used.
f4507f3 @mansilladev More schema updates (auth.oauth.token.*) for location and param name; ad...
mansilladev authored
414
415 13. "param" is the parameter name for access token. This is valid only if the location value is "query"
5be5ffc @alexadkins OAuth2 documentation in README
alexadkins authored
416
f4507f3 @mansilladev More schema updates (auth.oauth.token.*) for location and param name; ad...
mansilladev authored
417 14. "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.
5be5ffc @alexadkins OAuth2 documentation in README
alexadkins authored
418
419 Additional Note: All redirect URIs for the Foursquare API & your
420 Foursqare app must be set through the Foursquare developer site.
421 For the iodocs Foursquare API test these URIs are :
422 "http://localhost:3000/foursquare", "http://localhost:3000/oauth2Success/foursquare"
423
424 For the Rdio API test, beta access to their new API is necessary.
425 The site for the beta API is: "http://www.rdio.com/developers/"
426
427
428
d5bf45d @mansilladev Readme file added.
mansilladev authored
429 API-LEVEL CONFIG DETAILS
430 ========================
431 For every API that is configured in *apiconfig.json* a JSON config file must exist.
432 You should look at the *./public/data/* directory for examples.
433
434 ### Example #1 - Explanation of each field in an example API-level configuration
435
04d86bc @kmiyashiro Remove line numbers, balancing braces, syntax highlighting.
kmiyashiro authored
436 ```js
437 {
8ff62fc @alexadkins Schema changes, request body capabilities, array types, & location enhan...
alexadkins authored
438 "name": "Lower Case API",
439 "protocol": "rest",
440 "basePath": "http://api.lowercase.sample.com",
441 "resources": {
442 "User Resources": {
443 "methods": {
444 "showUsers": {
445 "name": "users/show",
446 "description": "Returns extended user information",
447 "httpMethod": "GET",
448 "path": "/users/show.json",
449 "parameters": {
450 "user_id": {
451 "title":"user_id",
452 "required":true,
453 "default":"",
454 "type":"string",
455 "description":"The ID of the user"
456 },
457 "cereal": {
458 "title": "cereal",
459 "required": true,
460 "default": "fruitscoops",
461 "type": "string",
462 "enum": ["fruitscoops","sugarbombs","frostedteeth"],
463 "description": "The type of cereal desired."
464 },
465 "skip_status": {
466 "title": "skip_status",
467 "required": false,
468 "default": "false",
469 "type":"boolean",
470 "description":"If true, status not included."
471 "location": "header"
472 },
473 "include_status": {
474 "title": "include_status",
475 "required": false,
476 "default": false,
0648e42 @alexadkins Added documentation for textarea type
alexadkins authored
477 "type": "boolean",
8ff62fc @alexadkins Schema changes, request body capabilities, array types, & location enhan...
alexadkins authored
478 "description": "If true, status included."
479 "booleanValues": ["yes","no"]
0648e42 @alexadkins Added documentation for textarea type
alexadkins authored
480 },
481 "review": {
482 "title": "review",
483 "required": false,
484 "default": "",
485 "type": "textarea",
486 "description": "The user's review to submit."
8ff62fc @alexadkins Schema changes, request body capabilities, array types, & location enhan...
alexadkins authored
487 }
488 }
489 }
490 }
491 }
492 }
04d86bc @kmiyashiro Remove line numbers, balancing braces, syntax highlighting.
kmiyashiro authored
493 ```
d5bf45d @mansilladev Readme file added.
mansilladev authored
494
495 Line:
496
636ad29 @alexadkins Edited README
alexadkins authored
497 (1). "name" key value is a string that holds the name
8ff62fc @alexadkins Schema changes, request body capabilities, array types, & location enhan...
alexadkins authored
498 of the API that is used in the Jade template output. Also true in *apiconfig.json*.
499
636ad29 @alexadkins Edited README
alexadkins authored
500 (2). "protocol" key value is either *rest* or *soap*
8ff62fc @alexadkins Schema changes, request body capabilities, array types, & location enhan...
alexadkins authored
501
636ad29 @alexadkins Edited README
alexadkins authored
502 (3). "basePath" key value is the host path of
8ff62fc @alexadkins Schema changes, request body capabilities, array types, & location enhan...
alexadkins authored
503 the API calls
504
636ad29 @alexadkins Edited README
alexadkins authored
505 (4). "resources" JSON container. Methods are grouped into resources.
8ff62fc @alexadkins Schema changes, request body capabilities, array types, & location enhan...
alexadkins authored
506
636ad29 @alexadkins Edited README
alexadkins authored
507 (5). The first resource.
8ff62fc @alexadkins Schema changes, request body capabilities, array types, & location enhan...
alexadkins authored
508
636ad29 @alexadkins Edited README
alexadkins authored
509 (6). "methods" key value is an array of JSON objects (each one being a method)
8ff62fc @alexadkins Schema changes, request body capabilities, array types, & location enhan...
alexadkins authored
510
636ad29 @alexadkins Edited README
alexadkins authored
511 (7). The first method.
8ff62fc @alexadkins Schema changes, request body capabilities, array types, & location enhan...
alexadkins authored
512
636ad29 @alexadkins Edited README
alexadkins authored
513 (8). "name" key value is a string that is displayed via the view template. The name of the method.
8ff62fc @alexadkins Schema changes, request body capabilities, array types, & location enhan...
alexadkins authored
514
636ad29 @alexadkins Edited README
alexadkins authored
515 (9). "description" key value is a short description of the method.
8ff62fc @alexadkins Schema changes, request body capabilities, array types, & location enhan...
alexadkins authored
516
636ad29 @alexadkins Edited README
alexadkins authored
517 (10). "httpMethod" key value can be either GET, POST, DELETE or PUT (all caps)
8ff62fc @alexadkins Schema changes, request body capabilities, array types, & location enhan...
alexadkins authored
518
636ad29 @alexadkins Edited README
alexadkins authored
519 (11). "path" key value is the path to the method that is appended to the *baseURL* and the public/private path.
8ff62fc @alexadkins Schema changes, request body capabilities, array types, & location enhan...
alexadkins authored
520
636ad29 @alexadkins Edited README
alexadkins authored
521 (12). "parameters" key value is a JSON objects containing the parameters
8ff62fc @alexadkins Schema changes, request body capabilities, array types, & location enhan...
alexadkins authored
522
636ad29 @alexadkins Edited README
alexadkins authored
523 (13). The first parameter.
8ff62fc @alexadkins Schema changes, request body capabilities, array types, & location enhan...
alexadkins authored
524
636ad29 @alexadkins Edited README
alexadkins authored
525 (14). "title" key value is a string that contains the name of the parameter.
8ff62fc @alexadkins Schema changes, request body capabilities, array types, & location enhan...
alexadkins authored
526
636ad29 @alexadkins Edited README
alexadkins authored
527 (15). "required" key value is either true or false.
8ff62fc @alexadkins Schema changes, request body capabilities, array types, & location enhan...
alexadkins authored
528
636ad29 @alexadkins Edited README
alexadkins authored
529 (16). "default" key value is a string, containing a default value that will be automatically populated onto the form.
d5bf45d @mansilladev Readme file added.
mansilladev authored
530
636ad29 @alexadkins Edited README
alexadkins authored
531 (17). "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.
d5bf45d @mansilladev Readme file added.
mansilladev authored
532
636ad29 @alexadkins Edited README
alexadkins authored
533 (18). "description" key value is a string, containing the description of the parameter.
d5bf45d @mansilladev Readme file added.
mansilladev authored
534
636ad29 @alexadkins Edited README
alexadkins authored
535 (25). "enum" key value is an array of enumerated values that will render a drop-down (select box) on the form.
d5bf45d @mansilladev Readme file added.
mansilladev authored
536
636ad29 @alexadkins Edited README
alexadkins authored
537 (32). "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
538
636ad29 @alexadkins Edited README
alexadkins authored
539 (24). "location" (optional) key value determines where the parameter will go. Can be "query" or "header". Default to "query".
d5bf45d @mansilladev Readme file added.
mansilladev authored
540
636ad29 @alexadkins Edited README
alexadkins authored
541 (43). "booleanValues" is an array of [true, false] alternatives that will instead populate the drop down box.
d5bf45d @mansilladev Readme file added.
mansilladev authored
542
636ad29 @alexadkins Edited README
alexadkins authored
543 (49). "type" key value is *textarea* that will render a textarea box, a multi-line text input control.
0648e42 @alexadkins Added documentation for textarea type
alexadkins authored
544
d5bf45d @mansilladev Readme file added.
mansilladev authored
545
09a6606 @alexadkins Updated README
alexadkins authored
546 ### Example #2 - Request Bodies, Arrays, & Objects
8ff62fc @alexadkins Schema changes, request body capabilities, array types, & location enhan...
alexadkins authored
547
548 ```js
549 {
550 "name": "Lower Case API",
551 "protocol": "rest",
552 "basePath": "http://api.lowercase.sample.com",
553 "schemas": {
554 "showUsers": {
555 "properties": {
556 "bodyParam": {
557 "title":"bodyParam",
558 "required":true,
559 "default":"",
560 "type":"string",
561 "description":"An example parameter in the body"
562 },
563 "arrayExample": {
564 "type": "array",
565 "items": {
566 "title":"arrayExample",
567 "required": true,
568 "default": "foobar",
569 "type":"string",
570 "description":"An array in the body."
571 }
09a6606 @alexadkins Updated README
alexadkins authored
572 },
573 "objectExample": {
574 "type": "object",
575 "properties": {
576 "element1": {
577 "title": "element1",
578 "required":false,
579 "type":"string",
580 "description": "An element in a JSON object.",
581 "default": "el1"
582 },
583 "element2": {
584 "title": "element2",
585 "required":false,
586 "type":"string",
587 "description": "Second element in a JSON object.",
588 "default": "el2"
589 },
590 "subObjectEx": {
591 "type": "object",
592 "properties": {
593 "element3": {
594 "title": "element3",
595 "required":false,
596 "type":"string",
597 "description": "An element within an object within an object.",
598 "default": "el3"
599 }
600 }
601 }
602 }
8ff62fc @alexadkins Schema changes, request body capabilities, array types, & location enhan...
alexadkins authored
603 }
604 }
605 }
606 },
607 "resources": {
608 "User Resources": {
609 "methods": {
610 "showUsers": {
611 "name": "users/show",
612 "description": "Returns extended user information",
613 "httpMethod": "GET",
614 "path": "/users/show.json",
615 "request": {
616 "$ref": "showUsers"
617 },
618 "parameters": {
619 "user_id": {
620 "title":"user_id",
621 "required":true,
622 "default":"",
623 "type":"string",
624 "description":"The ID of the user"
625 }
626 }
627 }
628 }
629 }
630 }
631 ```
632
633 Line:
634
636ad29 @alexadkins Edited README
alexadkins authored
635 (4). "schemas" JSON object. Contains the parameters that will go into the request body for all methods.
d5bf45d @mansilladev Readme file added.
mansilladev authored
636
636ad29 @alexadkins Edited README
alexadkins authored
637 (5). The first method to contain a request body.
d5bf45d @mansilladev Readme file added.
mansilladev authored
638
636ad29 @alexadkins Edited README
alexadkins authored
639 (6). "properties" JSON object containing the parameters that will go into the request body.
d5bf45d @mansilladev Readme file added.
mansilladev authored
640
09a6606 @alexadkins Updated README
alexadkins authored
641 (7). The first request body parameter. The format is the same as in "resources"
d5bf45d @mansilladev Readme file added.
mansilladev authored
642
636ad29 @alexadkins Edited README
alexadkins authored
643 (14). An array parameter. An array parameter can add as many values to the parameter as necessary. The default location for an array will always be "body".
d5bf45d @mansilladev Readme file added.
mansilladev authored
644
636ad29 @alexadkins Edited README
alexadkins authored
645 (15). "type" key value set to *array*. Necessary for the array functionality to work.
d5bf45d @mansilladev Readme file added.
mansilladev authored
646
636ad29 @alexadkins Edited README
alexadkins authored
647 (16). "items" JSON object that contains the parameter information. Format is consistent from resources parameters.
d5bf45d @mansilladev Readme file added.
mansilladev authored
648
636ad29 @alexadkins Edited README
alexadkins authored
649 (24). A JSON object parameter.
09a6606 @alexadkins Updated README
alexadkins authored
650
636ad29 @alexadkins Edited README
alexadkins authored
651 (25). "type" key value set to *object*. Necessary for the object functionality to work.
09a6606 @alexadkins Updated README
alexadkins authored
652
636ad29 @alexadkins Edited README
alexadkins authored
653 (26). "properties" JSON object containing the parameters that will go into the object.
09a6606 @alexadkins Updated README
alexadkins authored
654
636ad29 @alexadkins Edited README
alexadkins authored
655 (41). An object embedded within an object.
09a6606 @alexadkins Updated README
alexadkins authored
656
636ad29 @alexadkins Edited README
alexadkins authored
657 (66). "request" JSON object holds the reference to the request body parameters
d5bf45d @mansilladev Readme file added.
mansilladev authored
658
636ad29 @alexadkins Edited README
alexadkins authored
659 (67). "$ref" key value is the reference to the same string in "schemas"
2f7b489 @martintajur support for EnumeratedDescription to better describe enumerated property...
martintajur authored
660
d5bf45d @mansilladev Readme file added.
mansilladev authored
661
662 SUPPORT
663 =======
9d399d8 @precision point users directly to the github issues page
precision authored
664 If you need any help with I/O Docs, you can reach out to us via the GitHub Issues page at:
665 <code>[http://github.com/mashery/iodocs/issues](http://github.com/mashery/iodocs/issues)</code>
Something went wrong with that request. Please try again.