forked from platanus/angular-restmod
-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathtutorial-integration.html
More file actions
505 lines (423 loc) · 18.9 KB
/
Copy pathtutorial-integration.html
File metadata and controls
505 lines (423 loc) · 18.9 KB
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
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>restmod tutorialintegration</title>
<!--[if lt IE 9]>
<script src="//html5shiv.googlecode.com/svn/trunk/html5.js"></script>
<![endif]-->
<link type="text/css" rel="stylesheet" href="styles/sunlight.default.css">
<link type="text/css" rel="stylesheet" href="styles/site.cerulean.css">
</head>
<body>
<div class="container-fluid">
<div class="navbar navbar-fixed-top ">
<div class="navbar-inner">
<a class="brand" href="index.html">restmod</a>
<ul class="nav">
<li class="dropdown">
<a href="classes.list.html" class="dropdown-toggle" data-toggle="dropdown">Classes<b
class="caret"></b></a>
<ul class="dropdown-menu ">
<li>
<a href="BuilderApi.html">BuilderApi</a>
</li>
<li>
<a href="CollectionApi.html">CollectionApi</a>
</li>
<li>
<a href="CommonApi.html">CommonApi</a>
</li>
<li>
<a href="DefaultPacker.html">DefaultPacker</a>
</li>
<li>
<a href="ExtendedApi.html">ExtendedApi</a>
</li>
<li>
<a href="ExtendedBuilderApi.html">ExtendedBuilderApi</a>
</li>
<li>
<a href="FastQ.html">FastQ</a>
</li>
<li>
<a href="ListApi.html">ListApi</a>
</li>
<li>
<a href="PackerCache.html">PackerCache</a>
</li>
<li>
<a href="RecordApi.html">RecordApi</a>
</li>
<li>
<a href="RelationBuilderApi.html">RelationBuilderApi</a>
</li>
<li>
<a href="RelationScope.html">RelationScope</a>
</li>
<li>
<a href="restmod.html">restmod</a>
</li>
<li>
<a href="restmodProvider.html">restmodProvider</a>
</li>
<li>
<a href="RMBuilderComputedApi.html">RMBuilderComputedApi</a>
</li>
<li>
<a href="ScopeApi.html">ScopeApi</a>
</li>
<li>
<a href="StaticApi.html">StaticApi</a>
</li>
<li>
<a href="Utils.html">Utils</a>
</li>
</ul>
</li>
<li class="dropdown">
<a href="mixins.list.html" class="dropdown-toggle" data-toggle="dropdown">Mixins<b
class="caret"></b></a>
<ul class="dropdown-menu ">
<li>
<a href="DebouncedModel.html">DebouncedModel</a>
</li>
<li>
<a href="DirtyModel.html">DirtyModel</a>
</li>
<li>
<a href="FindMany.html">FindMany</a>
</li>
<li>
<a href="NestedDirtyModel.html">NestedDirtyModel</a>
</li>
<li>
<a href="PagedModel.html">PagedModel</a>
</li>
<li>
<a href="Preload.html">Preload</a>
</li>
<li>
<a href="SharedModel.html">SharedModel</a>
</li>
</ul>
</li>
<li class="dropdown">
<a href="tutorials.list.html" class="dropdown-toggle" data-toggle="dropdown">Tutorials<b
class="caret"></b></a>
<ul class="dropdown-menu ">
<li>
<a href="tutorial-building.html">building</a>
</li>
<li>
<a href="tutorial-hooks.html">hooks</a>
</li>
<li>
<a href="tutorial-integration.html">integration</a>
</li>
<li>
<a href="tutorial-styles.html">styles</a>
</li>
</ul>
</li>
<li class="dropdown">
<a href="global.html" class="dropdown-toggle" data-toggle="dropdown">Global<b
class="caret"></b></a>
<ul class="dropdown-menu ">
<li>
<a href="global.html#dummy">dummy</a>
</li>
<li>
<a href="global.html#list">list</a>
</li>
</ul>
</li>
</ul>
</div>
</div>
<div class="row-fluid">
<div class="span12">
<div id="main">
<section>
<header>
<h2>integration</h2>
</header>
<article>
<h1>API Integration FAQ</h1>
<p>Make sure you read all of the following Q&A before you start integrating your API:</p>
<ul>
<li><a href="#q1">How can I change the property used for the primary key</a></li>
<li><a href="#q2">How do I handle a wrapped response object? (json root object)</a></li>
<li><a href="#q3">How can I extract response metadata from the root object?</a></li>
<li><a href="#q4">Does restmod supports linked elements side loaded in the response wrapper?</a></li>
<li><a href="#q5">My resource properties are being automatically renamed, is this normal?</a></li>
<li><a href="#q6">Are there any other conventions related to naming I should be aware of?</a></li>
<li><a href="#q7">How can I set a common url prefix for every resource?</a></li>
<li><a href="#q8">How can I add a trailing slash or extension to the url sent to server?</a></li>
<li><a href="#q9">How can I add a custom header or parameter to every request?</a></li>
<li><a href="#q10">I'm getting a 'No API style base was included' warning, what does it mean?</a></li>
<li><a href="#q11">Can I change the way url names are generated for relations?</a></li>
</ul>
<h3><a name="q1"></a> How can I change the property used for the primary key</h3>
<p>The primary key is just a model configuration property and by default is set to 'id'.</p>
<p>To change it for a particular model use the <code>$config</code> block:</p>
<pre><code class="lang-javascript">restmod.model('/bikes').$mix({
$config: { primaryKey: '_id' }
});</code></pre>
<p>Or for every model, just set a base model definition using <code>rebase</code>:</p>
<pre><code class="lang-javascript">module.config(function(restmodProvider) {
restmodProvider.rebase({
$config: {
primaryKey: '_id'
}
});
});</code></pre>
<h3><a name="q2"></a> How do I handle a wrapped response object? (json root object)</h3>
<p>In restmod response wrapping is handled by the model's <code>unpack</code> and <code>pack</code> static methods, by default this methods do nothing so records and collections are expected at response root level.</p>
<p>Restmod comes with a default packer mixin that should handle most situations, to enable the default packer just add the <code>DefaultPacker</code> mixin:</p>
<pre><code class="lang-javascript">module.config(function(restmodProvider) {
restmodProvider.rebase('DefaultPacker');
});</code></pre>
<p>This will enable json root wrapping and by default it will use the resource's name for single records and the resource's plural name for collections.</p>
<p>So doing:</p>
<pre><code class="lang-javascript">restmod.model('/api/bikes').$search();</code></pre>
<p>Will expect:</p>
<pre><code class="lang-json">{
"bikes": [{ "id": 1, "brand": "Trek" }]
}</code></pre>
<p>And doing:</p>
<pre><code class="lang-javascript">restmod.model('/api/bikes').$find(1);</code></pre>
<p>Will expect:</p>
<pre><code class="lang-json">{
"bike": { "id": 1, "brand": "Trek" }
}</code></pre>
<p>The resoure's name is extracted from the resource url, if no url is given (nested resource) or if url does not match the resource's name, then you can change it's name and plural name by setting the <code>name</code> and <code>plural</code> configuration variables:</p>
<pre><code class="lang-javascript">restmod.model().$mix(function() {
$config: {
name: 'mouse', // if you only set NAME, then plural is infered from it using the inflector.
plural: 'mice'
}
});</code></pre>
<p>It's also posible to change the root property name without changing the resource name by setting the <code>jsonRootSingle</code>, <code>jsonRootMany</code> or the <code>jsonRoot</code> (both single and many) configuration properties. This should only be used when the properties are fixed or not named after the resource.</p>
<h3><a name="q3"></a> How can I extract response metadata from the root object?</h3>
<p>Take a look at the <a href="#q2">previous question</a> first and set up the default packer mixin.</p>
<p>By default, the default packer <code>unpack</code> method extracts metadata from the <code>meta</code> root property and stores it in the record's (or collection's) <code>$metadata</code> property.</p>
<p>So, the following response to a collection's <code>$fetch</code>:</p>
<pre><code class="lang-json">{
"bikes": [{
"user_id": 1,
"part_ids": [1, 2, 3]
}],
"meta": {
"page": 1
}
}</code></pre>
<p>Will put <code>{ page: 1 }</code> in the collection's <code>$metadata</code> property.</p>
<p>To change the property from where the packer extracts the metadata set the <code>jsonMeta</code> configuration property. Set it to '.' to extract metadata from root, so given:</p>
<pre><code class="lang-json">{
"bikes": [{
"user_id": 1,
"part_ids": [1, 2, 3]
}],
"page": 1
}</code></pre>
<pre><code class="lang-javascript">var Bike = restmod.model('/api/bikes').$mix('DefaultPacker',
$config: {
jsonMeta: '.'
}
});
Bike.$search().$then(function(_colection) {
_colection.$metadata; // = { page: 1 } it will ignore response's bikes property.
})</code></pre>
<h3><a name="q4"></a> Does restmod supports linked elements side loaded in the response wrapper?</h3>
<p>Yes it does, at least if its formated similar to what active_model_serializer generates.</p>
<p>Take a look at the <a href="#q2">wrapped response question</a> first and set up the default packer.</p>
<p>By default, the default packer will expect inlined resources to come in a property named <code>linked</code> (jsonapi.org standard).</p>
<p>The following example shows a simple use case scenario:</p>
<p>Given the following api response for the resource <code>/api/bikes/:id</code></p>
<pre><code class="lang-json">{
"bike": {
"user_id": 1,
"part_ids": [1, 2, 3]
},
"linked": {
"users": [
{ "id": 1, "name": "Joe", "role": "admin" }
],
"parts": [
{ "id": 1, "name": "handlebar" },
{ "id": 2, "name": "lever" },
{ "id": 3, "name": "wheel" }
]
}
}</code></pre>
<p>The following model definition should correctly load every resource:</p>
<pre><code class="lang-javacript">var Base = restmod.mixin('DefaultPacker'); // remember to enable the default packer.
var User = restmod.model('/api/users').$mix(Base);
var Part = restmod.model('/api/parts').$mix(Base);
var Bike = restmod.model('/api/bikes').$mix(Base, {
user: { belongsTo: User },
parts: { belongsToMany: Part }
})
// Then calling
bike = Bike.$find(1).$then(function() {
bike.user.name; // = Joe
});</code></pre>
<p>To change the property where the inlined resources are located set the <code>jsonLinks</code> configuration property or set it to '.' to extract links from root.</p>
<pre><code class="lang-javascript">module.config(function(restmodProvider) {
restmodProvider.rebase(function() {
this.setProperty('jsonLinks', 'links'); // or set jsonLinks: 'links' in a definition object.
});
});</code></pre>
<p>Take a look at the default naming stardards, inlined resources are expected to use the <strong>pluralized</strong> names for their respective model names. See. By default the name is extracted from the url, you can change a model's name and plural name by setting the <code>name</code> and <code>plural</code> configuration variables:</p>
<pre><code class="lang-javascript">restmod.model().$mix(function() {
$config: {
name: 'mouse', // if you only set name, then plural is infered from it.
plural: 'mice'
}
});</code></pre>
<h3><a name="q5"></a> My resource properties are being automatically renamed, is this normal?</h3>
<p>That is probably because the api style you selected has overriden the model's property renaming methods <code>encodeName</code> and <code>decodeName</code>.</p>
<p>You can disable or modify renaming by overriding the following methods:</p>
<pre><code class="lang-javascript">module.config(function(restmodProvider) {
restmodProvider.rebase({
$extend: {
Model: {
encodeName: function(_name) { return _newName; }, // or null to disable renaming.
decodeName: function(_name) { return _newName; } // or null to disable renaming.
}
}
});
});</code></pre>
<h3><a name="q6"></a> Are there any other conventions related to naming I should be aware of?</h3>
<p>One last one!</p>
<p>By design, restmod will ignore response properties that start with '$' and won't send in requests local properties that start with '$'. This cannot be disabled.</p>
<p>To handle API's that require '$' prefixed properies you have two posibilities:</p>
<ol>
<li><p>Change the name decoder so it renames properties that start with '$' and gives them another prefix and then change the name encoder to detect the special prefix and change it back to '$':</p>
<pre><code class="lang-javascript"> module.config(function(restmodProvider) {
restmodProvider.rebase({
$extend: {
Model: {
decodeName: function(_name) {
// change prefix to '_'
return _name.charAt(0) == '$' ? '_' + inflector.camelize(_name.substr(1), true) : inflector.camelize(_name);
},
encodeName: function(_name) {
// change prefix back to '$'
return _name.charAt(0) == '_' ? '$' + inflector.parameterize(_name.substr(1), '_') : inflector.parameterize(_name, '_');
}
}
}
});
});</code></pre>
</li>
<li><p>if there are only a couple of properties you need to let through, assign a special mapping to those properties:</p>
<pre><code class="lang-javascript"> restmod.model().$mix({
myType: { map: '$type' },
myName: { map: '$name' }
})</code></pre>
</li>
</ol>
<h3><a name="q7"></a> How can I set a common url prefix for every resource?</h3>
<p>You can user the <code>urlPrefix</code> configuration property, like this:</p>
<pre><code class="lang-javascript">module.config(function(restmodProvider) {
restmodProvider.rebase({
$config: {
urlPrefix: '/api/v1' // or use setProperty('urlPrefix', '/api/v1') in a definition function
}
});
});</code></pre>
<h3><a name="q8"></a> How can I add a trailing slash or extension to the url sent to server?</h3>
<p>You can hook to the <code>before-request</code> event and modify the url before is sent, restmod will remove trailing slashes from generated urls before this hook is called, so slashes appended here will be sent.</p>
<pre><code class="lang-javascript">module.config(function(restmodProvider) {
restmodProvider.rebase({
$hooks: {
'before-request': function(_req) {
// _req is just a $http configuration object.
_req.url += '.json';
}
}
});
});</code></pre>
<p>You can read more about hooks and object lifecycle in the <a href="https://github.com/platanus/angular-restmod/blob/master/docs/guides/hooks.md">Hooks Guide</a>.</p>
<h3><a name="q9"></a> How can I add a custom header or parameter to every request?</h3>
<p>Same as before, you can hook to the <code>before-request</code> event:</p>
<pre><code class="lang-javascript">module.config(function(restmodProvider) {
restmodProvider.rebase({
$hooks: {
'before-request': function(_req) {
_req.headers = angular.extend(_req.headers, { 'X-My-Header': 'imateapot!' });
}
}
});
});</code></pre>
<h3><a name="q10"></a> I'm getting a 'No API style base was included' warning, what does it mean?</h3>
<p>Restmod expect you to use a base API style for your models, you should include one of the included styles or create a new one:</p>
<p>For example to use the active_model_serializer style you should include the <code>/dist/styles/ams.min.js</code> file in your project and then:</p>
<pre><code class="lang-javascript">module.config(function(restmodProvider) {
restmodProvider.rebase('AMSApi');
});</code></pre>
<p>or to define your own style do:</p>
<pre><code class="lang-javascript">module.config(function(restmodProvider) {
restmodProvider.rebase({
$config: {
style: 'MyDjangoStyle', // By setting the style variable the warning is disabled.
primaryKey: '_id'
/* other style related configuration */
}
});
});</code></pre>
<p>To see available styles or colaborate with a new one, take a look at the <a href="https://github.com/platanus/angular-restmod/blob/master/docs/guides/styles.md">Style listing</a>.</p>
<h3><a name="q11"></a> Can I change the way url names are generated for relations?</h3>
<p>Yes you can, just override the <code>Model.encodeUrlName</code> method to provide custom name transformation, like this:</p>
<pre><code class="lang-javascript">module.config(function(restmodProvider) {
restmodProvider.rebase({
$extend: {
Model: {
encodeUrlName: function(_name) {
return _name.toLowerCase();
}
}
}
});
});</code></pre>
<p>Transformations will be applied to relations where the extended model is referenced.</p>
</article>
</section>
</div>
<div class="clearfix"></div>
<footer>
<span class="jsdoc-message">
Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.2.2</a>
on Wed Feb 18 2015 20:30:54 GMT-0300 (CLST) using the <a href="https://github.com/terryweiss/docstrap">DocStrap template</a>.
</span>
</footer>
</div>
<br clear="both">
</div>
</div>
<script src="scripts/sunlight.js"></script>
<script src="scripts/sunlight.javascript.js"></script>
<script src="scripts/sunlight-plugin.doclinks.js"></script>
<script src="scripts/sunlight-plugin.linenumbers.js"></script>
<script src="scripts/sunlight-plugin.menu.js"></script>
<script src="scripts/jquery.min.js"></script>
<script src="scripts/jquery.scrollTo.js"></script>
<script src="scripts/jquery.localScroll.js"></script>
<script src="scripts/bootstrap-dropdown.js"></script>
<script src="scripts/toc.js"></script>
<script> Sunlight.highlightAll({lineNumbers:true, showMenu: true, enableDoclinks :true}); </script>
<script>
$( function () {
$( "#toc" ).toc( {
selectors : "h1,h2,h3,h4",
showAndHide : false,
scrollTo : 60
} );
$( "#toc>ul" ).addClass( "nav nav-pills nav-stacked" );
$( "#main span[id^='toc']" ).addClass( "toc-shim" );
} );
</script>
</body>
</html>