-
Notifications
You must be signed in to change notification settings - Fork 11
/
Copy pathmethods.html
270 lines (253 loc) · 18.8 KB
/
methods.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
<div id="legend">
<ul>
<li><a href="#constructor">Constructor</a></li>
<li><a href="#method_connect">connect</a></li>
<li><a href="#method_contentType">contentType</a></li>
<li><a href="#method_context">context</a></li>
<li><a href="#method_cors">cors</a></li>
<li><a href="#method_domain">domain</a></li>
<li><a href="#method_format">format</a></li>
<li><a href="#method_getOverride">getOverride</a></li>
<li><a href="#method_jsonp">jsonp</a></li>
<li><a href="#method_option">option</a></li>
<li><a href="#method_options">options</a></li>
<li><a href="#method_param">param</a></li>
<li><a href="#method_params">params</a></li>
<li><a href="#method_port">port</a></li>
<li><a href="#method_postOverride">postOverride</a></li>
<li><a href="#method_protocol">protocol</a></li>
<li><a href="#method_resource">resource</a></li>
<li><a href="#method_timeout">timeout</a></li>
</ul>
</div>
<div class="method" id="method_connect">
<h3 class="monospace name">connect<span class="arguments">(<span class="monospace required parameter" title="Required argument">route</span>, <span class="monospace optional parameter" title="Optional argument">options</span>)</span></h3>
<p class="description">
<span class="short">Connects the route.</span>
<span class="extra">This is the main workhorse of APIConnect. <span class="monospace required parameter">route</span> is the route to be called, it can have the 4 HTTP verbs GET, POST, PUT, or DELETE preceding it, and it can also contain the format (.json, etc). <span class="monospace optional parameter">options</span> is an object that contains the options for the route. Any options here will be merged into the options passed when calling the route. Additionally there are 2 special options: <span class="code">params</span> will "burn in" any parameters so that they will always be passed when the route is called. <span class="code">as</span> will override the resulting method name, which by default is a camel-case form of the human-readable method (get, create, update, or destroy) plus the last fragment in the route. For example, <span class="code">connect('GET friends/statuses')</span> will result in the method name <span class="code">getStatuses</span>.</span>
</p>
<p class="returns">
<span class="label">Returns:</span>
<span class="value">Instance</span>
</p>
<div class="code_example"><p class="single_code_example">api.connect('friends')</p>
<p class="single_code_example">api.connect('POST friends')</p>
<p class="single_code_example">api.connect('PUT friends')</p>
<p class="single_code_example">api.connect('DELETE friends')</p>
<p class="single_code_example">api.connect('friends', { as 'fetchPeople' })</p>
<p class="single_code_example">api.connect('search', { params: { complete: true }, as: 'findCompleted' })</p></div>
</div>
<div class="method" id="method_contentType">
<h3 class="monospace name">contentType<span class="arguments">(<span class="monospace optional parameter" title="Optional argument">setting</span>)</span></h3>
<p class="description">
<span class="short">Gets or sets the contentType. Default is <span class="code">form</span>.</span>
<span class="extra">If the server requires a special contentType for parameter data, this can be specified here. Currently only <span class="code">form</span> and <span class="code">json</span> are supported. If the content type is "form", the standard <span class="code">key=value</span> parameter serialization format will be used. If the contentType is <span class="code">json</span>, the mime-type will be changed to <span class="code">application/json</span>. In this case params need to be passed as a string, otherwise APIConnect will attempt to stringify them using <span class="code">JSON.stringify</span>, which will fail in older browsers if not available. If you need this functionality a proper JSON shim should be used such as https://github.com/douglascrockford/JSON-js.</span>
</p>
<p class="returns">
<span class="label">Returns:</span>
<span class="value">Setting or Instance</span>
</p>
<div class="code_example"><p class="single_code_example">api.contentType('json')</p>
<p class="single_code_example">api.contentType()</p></div>
</div>
<div class="method" id="method_context">
<h3 class="monospace name">context<span class="arguments">(<span class="monospace required parameter" title="Required argument">name</span>, <span class="monospace required parameter" title="Required argument">callback</span>)</span></h3>
<p class="description">
<span class="short">Allows a callback inside which the context <span class="monospace required parameter">name</span> will be prepended.</span>
<span class="extra">If you have multiple routes with the same context, use this so that it doesn't have to be added to every <span class="code">connect</span> statement.</span>
</p>
<p class="returns">
<span class="label">Returns:</span>
<span class="value">Nothing</span>
</p>
<div class="code_example"><p class="single_code_example">api.context('friends', function() {
api.connect('posts');
api.connect('photos');
api.connect('events');
});</p></div>
</div>
<div class="method" id="method_cors">
<h3 class="monospace name">cors<span class="arguments">(<span class="monospace optional parameter" title="Optional argument">setting</span>)</span></h3>
<p class="description">
<span class="short">Gets or sets the CORS (cross-origin resource sharing) setting. Default is <span class="code">true</span>.</span>
<span class="extra">When active, APIConnect will attempt to make cross-browser ajax requests. JSONP will be used instead if the API is not on the same domain and the browser does not support CORS. Setting this to <span class="code">false</span> will turn off CORS support for all browsers. Note that CORS needs to be enabled on the server-side as well. If the API you're trying to connect to does not support this feature it should be turned off.</span>
</p>
<p class="returns">
<span class="label">Returns:</span>
<span class="value">Setting or Instance</span>
</p>
<div class="code_example"><p class="single_code_example">api.cors(false)</p>
<p class="single_code_example">api.cors()</p></div>
</div>
<div class="method" id="method_domain">
<h3 class="monospace name">domain<span class="arguments">(<span class="monospace optional parameter" title="Optional argument">setting</span>)</span></h3>
<p class="description">
<span class="short">Gets or sets the domain.</span>
<span class="extra">The domain can also be set when creating a new instance of APIConnect by passing a string as the first argument to the constructor.</span>
</p>
<p class="returns">
<span class="label">Returns:</span>
<span class="value">Setting or Instance</span>
</p>
<div class="code_example"><p class="single_code_example">api.domain('graph.facebook.com')</p>
<p class="single_code_example">api.domain()</p></div>
</div>
<div class="method" id="method_format">
<h3 class="monospace name">format<span class="arguments">(<span class="monospace required parameter" title="Required argument">dataFormat</span>, <span class="monospace optional parameter" title="Optional argument">appendFormat</span>)</span></h3>
<p class="description">
<span class="short">Gets or sets the format.</span>
<span class="extra"><span class="monospace required parameter">dataFormat</span> is the format passed to the AJAX library. By default this is JSON, so the result will be parsed as JSON. <span class="monospace optional parameter">appendFormat</span> is the format appended to each route. By default this is <span class="code">false</span>, so no format will be appended. If <span class="code">true</span> it will use the <span class="monospace required parameter">dataFormat</span>, and if anything else it will use it as the appended format instead.</span>
</p>
<p class="returns">
<span class="label">Returns:</span>
<span class="value">Setting or Instance</span>
</p>
<div class="code_example"><p class="single_code_example">api.format()</p>
<p class="single_code_example">api.format('xml', 'php')</p></div>
</div>
<div class="method" id="method_getOverride">
<h3 class="monospace name">getOverride<span class="arguments">(<span class="monospace optional parameter" title="Optional argument">setting</span>)</span></h3>
<p class="description">
<span class="short">Gets or sets the "getOverride" option.</span>
<span class="extra">This option turns all POST, PUT, and DELETE requests into GET and instead sets a <span class="code">_method</span> parameter representing the true method. <span class="monospace required parameter">setting</span> can be <span class="code">always</span>, which always adds <span class="code">_method</span>, <span class="code">jsonp</span>, which only overrides when using JSONP, <span class="code">always-except-get</span>, or <span class="code">jsonp-except-get</span>, which do the same except do not override GET methods, which typically do not require a <span class="code">_method</span> parameter.</span>
</p>
<p class="returns">
<span class="label">Returns:</span>
<span class="value">Setting or Instance</span>
</p>
<div class="code_example"><p class="single_code_example">api.getOverride()</p>
<p class="single_code_example">api.getOverride('always')</p></div>
</div>
<div class="method" id="method_jsonp">
<h3 class="monospace name">jsonp<span class="arguments">(<span class="monospace optional parameter" title="Optional argument">setting</span>)</span></h3>
<p class="description">
<span class="short">Gets or sets the JSONP setting. Default is <span class="code">true</span>.</span>
<span class="extra">When active, APIConnect will attempt to make JSONP requests if CORS is disabled or not available, and if the API is not the same domain. Note that JSONP needs to be enabled on the server-side as well. If the API you're trying to connect to does not support this feature it should be turned off.</span>
</p>
<p class="returns">
<span class="label">Returns:</span>
<span class="value">Setting or Instance</span>
</p>
<div class="code_example"><p class="single_code_example">api.jsonp(false)</p>
<p class="single_code_example">api.jsonp()</p></div>
</div>
<div class="method" id="method_option">
<h3 class="monospace name">option<span class="arguments">(<span class="monospace required parameter" title="Required argument">name</span>, <span class="monospace optional parameter" title="Optional argument">value</span>)</span></h3>
<p class="description">
<span class="short">Gets or sets a default option.</span>
<span class="extra">Default options are merged into the local options of all routes when called, and apply to all connected routes. Instance-wide options are always merged in last, ie. local options will always override them, so they can also be thought of as defaults.</span>
</p>
<p class="returns">
<span class="label">Returns:</span>
<span class="value">Setting or Instance</span>
</p>
<div class="code_example"><p class="single_code_example">api.option('port', 3000)</p>
<p class="single_code_example">api.option('port')</p></div>
</div>
<div class="method" id="method_options">
<h3 class="monospace name">options<span class="arguments">(<span class="monospace optional parameter" title="Optional argument">obj</span>)</span></h3>
<p class="description">
<span class="short">Gets or sets the default options.</span>
<span class="extra">Calls <span class="code">option</span> for each key/value pair in <span class="monospace optional parameter">obj</span>. When called without any arguments returns all default options.</span>
</p>
<p class="returns">
<span class="label">Returns:</span>
<span class="value">Setting or Instance</span>
</p>
<div class="code_example"><p class="single_code_example">api.options({ port: 3000 })</p>
<p class="single_code_example">api.options()</p></div>
</div>
<div class="method" id="method_param">
<h3 class="monospace name">param<span class="arguments">(<span class="monospace required parameter" title="Required argument">name</span>, <span class="monospace optional parameter" title="Optional argument">value</span>)</span></h3>
<p class="description">
<span class="short">Gets or sets a default parameter.</span>
<span class="extra">Default parameters are added to all routes. This is useful for things like API keys or access tokens that need to be used in every API call.</span>
</p>
<p class="returns">
<span class="label">Returns:</span>
<span class="value">Setting or Instance</span>
</p>
<div class="code_example"><p class="single_code_example">api.param('api_key', 'foo')</p>
<p class="single_code_example">api.param('api_key')</p></div>
</div>
<div class="method" id="method_params">
<h3 class="monospace name">params<span class="arguments">(<span class="monospace optional parameter" title="Optional argument">obj</span>)</span></h3>
<p class="description">
<span class="short">Gets or sets the default parameters.</span>
<span class="extra">Calls <span class="code">param</span> for each key/value pair in <span class="monospace optional parameter">obj</span>. When called without any arguments returns all default params.</span>
</p>
<p class="returns">
<span class="label">Returns:</span>
<span class="value">Setting or Instance</span>
</p>
<div class="code_example"><p class="single_code_example">api.param({ api_key: 'foo' })</p>
<p class="single_code_example">api.param()</p></div>
</div>
<div class="method" id="method_port">
<h3 class="monospace name">port<span class="arguments">(<span class="monospace optional parameter" title="Optional argument">setting</span>)</span></h3>
<p class="description">
<span class="short">Gets or sets the port. Default is <span class="code">null</span>.</span>
<span class="extra"></span>
</p>
<p class="returns">
<span class="label">Returns:</span>
<span class="value">Setting or Instance</span>
</p>
<div class="code_example"><p class="single_code_example">api.port(3000)</p>
<p class="single_code_example">api.port()</p></div>
</div>
<div class="method" id="method_postOverride">
<h3 class="monospace name">postOverride<span class="arguments">(<span class="monospace required parameter" title="Required argument">setting</span>)</span></h3>
<p class="description">
<span class="short">Gets or sets the "postOverride" option.</span>
<span class="extra">Some APIs require a POST method to stand in for PUT and DELETE. This option turns all PUT and DELETE requests into POST with a <span class="code">_method</span> parameter representing the true method. <span class="monospace required parameter">setting</span> can be <span class="code">true</span> or <span class="code">false</span>.</span>
</p>
<p class="returns">
<span class="label">Returns:</span>
<span class="value">Setting or Instance</span>
</p>
<div class="code_example"><p class="single_code_example">api.postOverride()</p>
<p class="single_code_example">api.postOverride(true)</p></div>
</div>
<div class="method" id="method_protocol">
<h3 class="monospace name">protocol<span class="arguments">(<span class="monospace optional parameter" title="Optional argument">setting</span>)</span></h3>
<p class="description">
<span class="short">Gets or sets the default protocol. Default is "auto".</span>
<span class="extra">When set to "auto", https will be used if the current page is using https, or if a param like "token", "access_token", or "oauth_token" is found in the params. Otherwise will use http.</span>
</p>
<p class="returns">
<span class="label">Returns:</span>
<span class="value">Setting or Instance</span>
</p>
<div class="code_example"><p class="single_code_example">api.protocol('https')</p>
<p class="single_code_example">api.protocol()</p></div>
</div>
<div class="method" id="method_resource">
<h3 class="monospace name">resource<span class="arguments">(<span class="monospace required parameter" title="Required argument">name</span>, <span class="monospace optional parameter" title="Optional argument">options</span>)</span></h3>
<p class="description">
<span class="short">Shortcut for connecting multiple routes for the same resource.</span>
<span class="extra">For singular resources it will connect 4 routes, GET, POST, UPDATE, and DELETE as get<span class="monospace required parameter">Name</span>, create<span class="monospace required parameter">Name</span>, update<span class="monospace required parameter">Name</span>, and destroy<span class="monospace required parameter">Name</span>. For plural routes it will add <span class="code">/:id</span> to the URL and singularize the method name for the above routes, and add an fifth "index" route without the <span class="code">/:id</span> fragment using non-singular method name. Singular/plural routes will attempt to be intelligently detected by finding the singularized form of <span class="monospace required parameter">name</span>. For non-countable or irregular nouns, instead pass <span class="code">{ collection: true }</span> in <span class="monospace optional parameter">options</span> to force plural routes. Additionally, <span class="code">only</span> and <span class="code">except</span> are allowed in <span class="monospace optional parameter">options</span> to limit the routes connected. Both can be either an array or comma-delimited string. Note that when limiting connected routes, <span class="code">index</span> and <span class="code">show</span> are used instead of <span class="code">get</span> to differentiate between singular and plural <span class="code">get</span> routes to be connected. This is only applicable to the <span class="code">resource</span> method.</span>
</p>
<p class="returns">
<span class="label">Returns:</span>
<span class="value">Instance</span>
</p>
<div class="code_example"><p class="single_code_example">api.resource('tweet')</p>
<p class="single_code_example">api.resource('tweets')</p>
<p class="single_code_example">api.resource('tweets', { only: 'show,create' })</p>
<p class="single_code_example">api.resource('tweets', { except: 'show,create' })</p>
<p class="single_code_example">api.resource('equipment', { collection: true })</p></div>
</div>
<div class="method" id="method_timeout">
<h3 class="monospace name">timeout<span class="arguments">(<span class="monospace optional parameter" title="Optional argument">setting</span>)</span></h3>
<p class="description">
<span class="short">Gets or sets the timeout. Default is <span class="code">30000</span>.</span>
<span class="extra">This option will be merged into the params passed to jQuery $.ajax, and tells it when to timeout an ajax request.</span>
</p>
<p class="returns">
<span class="label">Returns:</span>
<span class="value">Setting or Instance</span>
</p>
<div class="code_example"><p class="single_code_example">api.timeout(10000)</p>
<p class="single_code_example">api.timeout()</p></div>
</div>