-
Notifications
You must be signed in to change notification settings - Fork 0
/
index.html
444 lines (392 loc) · 19.8 KB
/
index.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
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
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>Nobody Understands REST but it is ok | William Durand</title>
<link rel="stylesheet" href="reveal.js/css/reveal.min.css">
<link rel="stylesheet" href="css/theme/mozilla/mozilla-blue.css" id="theme">
<!-- For syntax highlighting -->
<link rel="stylesheet" href="reveal.js/lib/css/zenburn.css">
<link rel="stylesheet" href="font-awesome/css/font-awesome.min.css">
<link rel="stylesheet" href="css/custom.css">
<script>
if (window.location.search.match(/print-pdf/gi)) {
document.write('<link rel="stylesheet" href="css/pdf.css" type="text/css">');
}
</script>
<!--[if lt IE 9]>
<script src="reveal.js/lib/js/html5shiv.js"></script>
<![endif]-->
</head>
<body>
<div class="reveal">
<div class="slides">
<section>
<h1 class="title">Nobody Understands REST<br><small>but it is ok ;-)</small></h1>
<em>William Durand - May 12th, 2015</em>
</section>
<section>
<section data-markdown>
<script type="text/template">
## A Few Words on REST
</script>
</section>
<section data-markdown>
<script type="text/template">
### **RE**presentational **S**tate **T**ransfer
REST is the underlying architectural principle of the web.
It is formalized as a set of **constraints**,
described in<br>**Roy Fielding**'s PhD dissertation.
</script>
</section>
<section data-markdown class="no-border">
<script type="text/template">
### **R**ichardson **M**aturity **M**odel
<p>
<small>
[http://martinfowler.com/articles/richardsonMaturityModel.html](http://martinfowler.com/articles/richardsonMaturityModel.html)
</small>
</p>
</script>
</section>
<section data-markdown>
<script type="text/template">
### Levels 0, 1, and 2
* It is all about **resources**
* **Client** uses specific HTTP **verbs**
* **Server** uses HTTP **status codes**
* Content Negotiation
</script>
</section>
<section data-markdown>
<script type="text/template">
### Level 3 - Hypermedia Controls
* Service discovery via **relations**
* **Hypermedia** formats (e.g. _HTML_, _HAL_, _JSON-LD_)
* Resources are not important, their **representations** are!
* URI design does **not** matter (URI template)
* **Client's experience** is crucial!
* Protocol & **application semantics**
</script>
</section>
<section data-markdown>
<script type="text/template">
### HATEOAS
**H**ypermedia **A**s **T**he **E**ngine **O**f **A**pplication **S**tate
<br>
<br>
It means that hypermedia should be used to find your
<br>way through the API. It is all about **state
transitions**.
Your application is just a big **state machine**.
</script>
</section>
<section data-markdown class="no-border no-margin">
<script type="text/template">
### Application State
</script>
</section>
<section data-markdown class="no-border">
<script type="text/template">
### Resource State
</script>
</section>
<section data-markdown>
<script type="text/template">
### Resource vs Representation
A **resource** can be anything, and can have<br>more than one representation.
<br>
<br>
A **representation** describes resource state.
</script>
</section>
<section data-markdown>
<script type="text/template">
### Protocol Semantics
How the underlying resource should behave under HTTP?
</script>
</section>
<section data-markdown>
<script type="text/template">
### Application Semantics
What **specifically** will happen to application or resource state?
</script>
</section>
<section data-markdown>
<script type="text/template">
### The Semantic Challenge<sup>*</sup>
Some standards have a good protocol-level
semantics<br>but no application-level
semantics (_Collection+JSON_, _Atom_).
<br>
<br>
Some standards define a lot of application-level semantics
<br>but no protocol semantics (_Microformats_, _Microdata_).
<br>
<small>* as described in Richardson and Amundsen's "RESTful Web APIs" book</small>
</script>
</section>
<section data-markdown>
<script type="text/template">
### Profiles
A **profile** is **defined** to not alter the semantics of the<br>resource representation
itself, but **to allow clients to<br>learn about additional semantics**, [RFC 6906](https://tools.ietf.org/html/rfc6906).
<br>
<br>
It does not have to be **machine-readable** but it is recommended.
</script>
</section>
<section data-markdown>
<script type="text/template">
### Examples
* Traditional API documentation
* _XMDP_ (for _XHTML_ documents)
* _**ALPS**_ (_XMDP_ on steroids)
* Embedded doc. (as in _HAL_/_Siren_)
* _**JSON-LD**_
</script>
</section>
</section>
<section>
<section data-markdown>
<script type="text/template">
## How To Design A Web API?
</script>
</section>
<section data-markdown>
<script type="text/template">
### 1. List The Semantic Descriptors
</script>
</section>
<section data-markdown>
<script type="text/template">
### 2. Draw A State Diagram
* Each "box" represents one kind of representation
* Arrows are the **state transitions** (HTTP requests)
* Change descriptors to relations when it makes sense
</script>
</section>
<section data-markdown>
<script type="text/template">
### 3. Use Strings From Existing Profiles
</script>
</section>
<section data-markdown>
<script type="text/template">
### 4. Choose A Media Type
Don't define your own, please.
</script>
</section>
<section data-markdown>
<script type="text/template">
### 5. Write A **Profile** That Documents<br>Your **Application Semantics**
</script>
</section>
<section data-markdown>
<script type="text/template">
### 6. Eat. Sleep. **Code.** Repeat.
</script>
</section>
<section data-markdown>
<script type="text/template">
### 7. Publish The "First" URL
</script>
</section>
<section data-markdown class="no-border">
<script type="text/template">
### <br>Mmmmh
</script>
</section>
</section>
<section>
<section data-markdown>
<script type="text/template">
## State Of The <strike>Art</strike> Industry
</script>
</section>
<section data-markdown>
<script type="text/template">
### We all want RESTful APIs
</script>
</section>
<section data-markdown>
<script type="text/template">
### Yes.
</script>
</section>
<section data-markdown>
<script type="text/template">
### Is My API RESTful When I Use JSON?
<br>
_[Short answer: no. Long answer: no, not yet.
<br>
RESTful API must use hypermedia formats.
JSON is<br>**not** a hypermedia
format](http://restcookbook.com/Mediatypes/json/),
The REST CookBook_.
</script>
</section>
<section data-markdown>
<script type="text/template">
### s/REST/HTTP++/
REST APIs are a myth, i.e. too complex in real life.
<br>
_[99.99% of the RESTful APIs out there aren’t fully
compliant<br>with Roy Fielding’s conception of
REST](http://www.timelessrepo.com/haters-gonna-hateoas), Steve Klabnik_.
</script>
</section>
<section data-markdown>
<script type="text/template">
### No Relations = No REST
<br>
_[If the engine of application state (and hence the
API)<br>is not being driven by hypertext, then it
cannot be<br>RESTful and cannot be a REST API](http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven), Roy Fielding_.
</script>
</section>
<section data-markdown>
<script type="text/template">
### Does It Matter?
</script>
</section>
</section>
<section>
<section data-markdown>
<script type="text/template">
## Beyond The Constraints
</script>
</section>
<section data-markdown>
<script type="text/template">
### Often Too Much
* How many **clients** do you have?
* Do you know any RESTful client?
* Writing smart clients is complicated
</script>
</section>
<section data-markdown>
<script type="text/template">
### Real Life #1
[Because of multiple round-trips and over-fetching,<br>applications built in the
REST style end up building<br>ad hoc endpoints](https://facebook.github.io/react/blog/2015/05/01/graphql-introduction.html), Facebook (on Relay/GraphQL).
</script>
</section>
<section data-markdown>
<script type="text/template">
### Real Life #2
[Pure REST: Slow, hard to program, and rare](http://extensionengine.com/netflix-moves-away-from-rest-for-its-api/), Netflix.
</script>
</section>
<section data-markdown>
<script type="text/template">
### Introducing HTTP++ APIs
Well-designed, pragmatic, and future-proof APIs.
</script>
</section>
<section data-markdown>
<script type="text/template">
### Design your API from a client perspective
</script>
</section>
<section data-markdown>
<script type="text/template">
### Think in terms of **representations**
</script>
</section>
<section data-markdown>
<script type="text/template">
### Stick to HTTP
</script>
</section>
<section data-markdown>
<script type="text/template">
### Still really want to build a RESTful API?
Choose the _**JSON-LD**_ format.
</script>
</section>
</section>
<section>
<section data-markdown>
<script type="text/template">
## So What?
</script>
</section>
<section data-markdown>
<script type="text/template">
### It is ok not to build RESTful APIs
</script>
</section>
<section data-markdown>
<script type="text/template">
### "REST" is a (marketing) buzzword
</script>
</section>
<section data-markdown>
<script type="text/template">
### REST is **not a silver bullet**
</script>
</section>
</section>
<section data-markdown>
<script type="text/template">
## Thank You.
### Questions?
<br>
<br>
<br>
<ul class="me">
<li>
<p><i class="fa fa-comments-o"></i><a href="https://joind.in/14276" title="joindin">joind.in/14276</a></p>
</li>
<li>
<p><i class="fa fa-globe"></i><a href="http://williamdurand.fr" title="website">williamdurand.fr</a></p>
</li>
<li>
<p><i class="fa fa-github"></i><a href="https://github.com/willdurand" title="github">github.com/willdurand</a></p>
</li>
<li>
<p><i class="fa fa-twitter"></i><a href="https://twitter.com/couac" title="twitter">twitter.com/couac</a></p>
</li>
</ul>
</script>
</section>
<section data-markdown>
<script type="text/template">
### Links
* [Hypertext Application Language](http://stateless.co/hal_specification.html)
* [JSON-LD](http://json-ld.org/)
* [Collection+JSON](http://amundsen.com/media-types/collection/)
* [Microformats](http://microformats.org/)
* [XHTML Meta Data Profiles](http://gmpg.org/xmdp/)
* [Application Language Profile Specification](http://alps.io/spec/)
* [Microdata](http://www.w3.org/TR/microdata/)
* [Siren](https://github.com/kevinswiber/siren)
* [http://restfulwebapis.com/](http://restfulwebapis.com/)
</script>
</section>
</div>
</div>
<script type="text/javascript" src="reveal.js/lib/js/head.min.js"></script>
<script type="text/javascript" src="reveal.js/js/reveal.min.js"></script>
<script type="text/javascript">
Reveal.initialize({
slideNumber: !window.location.search.match(/print-pdf/gi),
history: true,
theme: Reveal.getQueryHash().theme,
transition: Reveal.getQueryHash().transition || 'concave',
dependencies: [
{ src: 'reveal.js/lib/js/classList.js', condition: function() { return !document.body.classList; } },
{ src: 'reveal.js/plugin/markdown/marked.js', condition: function() { return !!document.querySelector( '[data-markdown]' ); } },
{ src: 'reveal.js/plugin/markdown/markdown.js', condition: function() { return !!document.querySelector( '[data-markdown]' ); } },
{ src: 'js/highlight.js', async: true, callback: function() { hljs.initHighlightingOnLoad(); } },
]
});
</script>
</body>
</html>