-
Notifications
You must be signed in to change notification settings - Fork 2
/
Copy pathlecture5.html
1018 lines (959 loc) · 34.8 KB
/
lecture5.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
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
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!DOCTYPE html>
<!--
Middleware and Web Services, CTU course slides
(cc) 2010-2023 Tomas Vitvar, http://vitvar.com
written for Humla, an open source HTML5 presentation environment
-->
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<meta name="course" content="Middleware Architectures 1" />
<meta name="lecture" content="Lecture 6" />
<meta name="keywords" content="SOA, service concepts, service technologies, SOAP, REST, WSDL" />
<link type="text/css" rel="stylesheet" href="css/meta.css">
</link>
<link type="text/css" rel="stylesheet" href="css/ctu-fit.css">
</link>
<link type="text/css" rel="stylesheet" href="humla/lib/core/humla.css">
</link>
<script type="text/javascript" src="humla/lib/humla.js"></script>
<title>Representational State Transfer</title>
</head>
<body>
<footer>
<p><b>#META_LECTURE#: #TITLE#</b>, <span class="meta_semester" />,
<span class="meta_twitter" />
</p>
<p><b>‒ #SLIDE_NO# ‒</b></p>
</footer>
<div class="slide intro">
<hgroup>
<h1><span class="meta_course" /></h1>
<h2>#META_LECTURE#: #TITLE#</h2>
</hgroup>
<div class="author">
<p class="meta_author" />
<p><span class="meta_email" /> • <span class="meta_twitter" /> •
<span class="meta_web" />
</p>
</div>
<center>
<div class="meta_logo"></div>
</center>
<div class="org">
<p class="meta_org" />
<p><span class="meta_orgfac" /> • <span class="meta_field" />
• <span class="meta_orgweb" /></p>
</div>
<div class="etc">
<div class="text-info">
Modified: #LAST_MODIFIED#<br />
Humla v#HUMLA_VERSION#
</div>
<a href="http://creativecommons.org/licenses/by-sa/3.0/">
<div class="license"></div>
</a>
<div class="oppa"></div>
</div>
</div>
<div class="slide outline"></div>
<section>
<header>Introduction to REST</header>
<div class="slide">
<hgroup>
<h1>Data on the Web</h1>
</hgroup>
<div class="h-drawing" style="height: 450px" id="161LY9K1fWd-G3iNpulEEEXq1yoxvjsQxombdyV4Yyfc"></div>
</div>
<div class="slide">
<hgroup>
<h1>REST</h1>
</hgroup>
<ul class="small spacing">
<li>REST</li>
<ul>
<li>Representational State Transfer</li>
</ul>
<li>Architecture Style</li>
<ul>
<li>Roy Fielding – co-author of HTTP</li>
<li>He coined REST in his <span class="h-ref" id="rest">PhD thesis</span>.</li>
<ul>
<li>The thesis abstracts from HTTP technical details</li>
<li>HTTP is one of the REST implementation → <b>RESTful</b></li>
<li>REST is a leading programming model for Web APIs</li>
</ul>
</ul>
<li>REST (RESTful) proper design</li>
<ul>
<li>people break principles often</li>
<li>See <span class="h-ref" id="rest-anti">REST Anti-Patterns</span> for some details.<br />
</ul>
<li>REST and Web Service Architecture</li>
<ul>
<li>REST is a realization of WSA resource-oriented model</li>
</ul>
</ul>
</div>
<div class="slide">
<hgroup>
<h1>REST and Web Architecture</h1>
</hgroup>
<ul class="small">
<li>Tim-Berners Lee</li>
<ul>
<li>"creator", father of the Web</li>
</ul>
<li>Key Principles</li>
<ul>
<li>Separation of Concerns</li>
<ul>
<li>enables independent innovation</li>
</ul>
<li>Standards-based</li>
<ul>
<li>common agreement, big spread and adoption</li>
</ul>
<li>Royalty-free technology</li>
<ul>
<li>a lot of open source, no fees</li>
</ul>
</ul>
<li>Architectural Basis</li>
<ul>
<li><b>Identification:</b> universal linking of resources using URI</li>
<li><b>Interaction:</b> protocols to retrieve resources – HTTP</li>
<li><b>Formats:</b> resource representation (data and metadata)</li>
</ul>
</ul>
</div>
<div class="slide">
<hgroup>
<h1>HTTP Advantages</h1>
</hgroup>
<ul class="small spacing">
<li>Familiarity</li>
<ul>
<li>HTTP protocol is well-known and widely used</li>
</ul>
<li>Interoperability</li>
<ul>
<li>All environments have HTTP client libraries</li>
<ul>
<li>technical interoperability is thus no problem</li>
<li>no need to deal with vendor-specific interoperability issues</li>
</ul>
<li>You can focus on the core of the integration problem</li>
<ul>
<li>application (domain, content) interoperability</li>
</ul>
</ul>
<li>Scalability</li>
<ul>
<li>you can use highly scalable Web infrastructure</li>
<ul>
<li>caching servers, proxy servers, etc.</li>
</ul>
<li>HTTP features such as HTTP GET idempotence and safe
allow you to use caching</li>
</ul>
</ul>
</div>
<div class="slide">
<hgroup>
<h1>REST Core Principles</h1>
</hgroup>
<ul class="small">
<li>REST architectural style defines constraints</li>
<ul>
<li>if you follow them, they help you to achieve a good design,
interoperability and scalability.</li>
</ul>
<li>Constraints</li>
<ul>
<li>Client/Server</li>
<li>Statelessness</li>
<li>Cacheability</li>
<li>Layered system</li>
<li>Uniform interface</li>
</ul>
<li>Guiding principles</li>
<ul>
<li>Identification of resources</li>
<li>Representations of resources and self-descriptive messages</li>
<li>Hypermedia as the engine of application state (HATEOAS)</li>
</ul>
</ul>
</div>
<div class="slide">
<hgroup>
<h1>Resource</h1>
</hgroup>
<ul class="x-small">
<li>A resource can be anything such as</li>
<ul>
<li>A real object: car, dog, Web page, printed document</li>
<li>An abstract thing such as address, name, etc. → RDF</li>
</ul>
<li>A resource in REST</li>
<ul>
<li>A resource corresponds to one or more entities of a data model</li>
<li>A representation of a resource can be conveyed in a message electronically (information resource)</li>
<li>A resource has an identifier and a representation and a client can apply an access to it</li>
</ul>
</ul>
<div class="h-drawing" style="height: 200px" id="1sSCJVFnKU0UgLek_FlFdQfKVeT9myKf-34IYyw5FQps"></div>
</div>
<div class="slide">
<hgroup>
<h1>Access to a Resource</h1>
</hgroup>
<div class="h-drawing" style="height: 290px;" id="1hw7HbAaK09w3I1mtmsJZMb3_OsYpFlBrrJjJRGsz23g"></div>
<ul class="x-small">
<li>Terminology</li>
<ul>
<li>Client = User Agent</li>
<li><b>Dereferencing URI</b> – a process of obtaining a protocol from the URI and creating a request.
</li>
<li><b>Access</b> – a process of sending a request and obtaining a response as a result;
access usually realized through HTTP.</li>
</ul>
</ul>
</div>
</section>
<div class="slide outline"></div>
<section>
<header>Uniform Resource Identifier</header>
<div class="slide">
<hgroup>
<h1>URI, URL, URN</h1>
</hgroup>
<ul class="small spacing">
<li>URI – Uniform Resource Identifier</li>
<ul>
<li>URI only identifies a resource</li>
<ul>
<li>it does not imply the resource physically exists</li>
</ul>
<li>URI could be URL (locator) or URN (name)</li>
</ul>
<li>URL – Uniform Resource Locator</li>
<ul>
<li>in addition allows to locate the resource</li>
<ul>
<li>that is — its network location</li>
</ul>
<li>every URL is URI but an URI does not need to be URL</li>
</ul>
<li>URN – Uniform Resource Name</li>
<ul>
<li>refers to URI under "urn" scheme (<span class="h-ref" id="rfc-2141">RFC 2141</span>)</li>
<li>require to be globally unique and persistent</li>
<ul>
<li>even if the resource cease to exist/becomes unavailable</li>
</ul>
</ul>
</ul>
</div>
<div class="slide">
<hgroup>
<h1>URI</h1>
</hgroup>
<ul class="x-small">
<li>Definition</li>
<pre class="brush: plain; gutter: 'false'; class-name: 'tight'">
URI = scheme ":" [ "//" authority ] [ "/" path ] [ "?" query ] [ "#" frag ]
</pre>
<li>Hierarchal sequence of components</li>
<ul>
<li><code>scheme</code></li>
<ul>
<li>refers to a spec that assigns IDs within that scheme</li>
<li>examples: <code>http</code>, <code>ftp</code>, <code>mailto</code>, <code>urn</code></li>
<li><code>scheme != protocol</code></li>
</ul>
<li><code>authority</code></li>
<ul>
<li>registered name (domain name) or server address</li>
<li>optional port and user</li>
</ul>
<li><code>path and query</code></li>
<ul>
<li>identify resource within the scheme and authority scope</li>
<li>path – hierarchal form</li>
<li>query – non-hierarchal form (parameters key=value)</li>
</ul>
<li><code>fragment</code></li>
<ul>
<li>reference to a secondary resource within the primary resource</li>
</ul>
</ul>
</ul>
</div>
<div class="slide">
<hgroup>
<h1>Resources over Entities</h1>
</hgroup>
<ul class="x-small">
<li>Application's data model</li>
<ul>
<li>Entities and properties that the app uses for its data</li>
</ul>
<div class="h-drawing" style="height: 290px" id="1zT46lCNzfiaw9d5HfA6fzDZFAj2GQG8sRAg1QRWPPfQ"></div>
<li>URI identifies a resource within the app's data model</li>
<ul>
<li><code>path</code> – a "view" on the data model</li>
<ul>
<li>data model is a graph</li>
<li>URI identifies a resource using a path in a tree with some root</li>
</ul>
</ul>
</ul>
</div>
<div class="slide">
<hgroup>
<h1>Examples of Views</h1>
</hgroup>
<ul class="x-small">
<li>View 1</li>
<ul>
<li>all customers: <code>/customers</code></li>
<li>a particular customer: <code>/customers/{customer-id}</code>
<li>All orders of a customer: <code>/customers/{customer-id}/orders</code>
<li>A particular order: <code>/customers/{customer-id}/orders/{order-id}</code>
</ul>
<li>View 2</li>
<ul>
<li>all orders: <code>/orders</code></li>
<li>All orders of a customer: <code>/orders/{customer-id}</code>
<li>A particular order: <code>/orders/{customer-id}/{order-id}</code>
</ul>
<li class="no-bullet">⇒ Design issues</li>
<li>Good design practices</li>
<ul>
<li>No need for 1:1 relationship between resources and data entities</li>
<ul>
<li>A resource may aggregate data from two or more entities</li>
<li>Thus only expose resources if it makes sense for the service</li>
</ul>
<li>Try to limit URI aliases, make it simple and clear</li>
</ul>
</ul>
</ul>
</div>
<div class="slide">
<hgroup>
<h1>Path vs. Query</h1>
</hgroup>
<ul class="x-small">
<li>Path</li>
<ul>
<li>Hierarchical component, a view on the data</li>
<li>The main identification of the resource</li>
</ul>
<li>Query</li>
<ul>
<li>Can define selection, projection or other processing instructions</li>
<li>Selection</li>
<ul>
<li>filters entries of a resource by values of properties<br />
<code>/customers/?status=valid</code>
</li>
</ul>
<li>Projection</li>
<ul>
<li>filters properties of resource entries<br />
<code>/customers/?properties=id,name</code>
</li>
</ul>
<li>Processing instructions examples</li>
<ul>
<li>data format of the resource → cf. URI opacity<br />
<code>/customers/?format=JSON</code>
</li>
<li>Access keys such as API keys<br />
<code>/customers/?key=3ae56-56ef76-34540aeb</code>
</li>
</ul>
</ul>
</ul>
</div>
<div class="slide">
<hgroup>
<h1>Fragment Semantics</h1>
</hgroup>
<ul class="small">
<li>Fragment semantics for HTML</li>
<ul>
<li>assume that <code>orders.html</code> are in <code>HTML</code> format.</li>
</ul>
<pre class="brush: plain">
http://company.com/tomas/orders.html#3456
</pre>
<ul>
<li class="no-bullet">⇒ there is a HTML element with <code>id=3456</code></li>
</ul>
<li>But:</li>
<ul>
<li>Consider <code>orders</code> resource in <code>application/xml</code></li>
</ul>
<pre class="brush: xml">
<orders>
<order id="3456">...</order>
...
</orders>
</pre>
<ul>
<li>Can't say that <code>http://company.com/tomas/orders.xml#3456</code> identifies
an order element within the <code>orders</code> resource.</li>
<li><code>application/xml</code> content type does not define fragment semantics</li>
</ul>
</ul>
</div>
<div class="slide">
<hgroup>
<h1>Major characteristics</li>
</hgroup>
<ul class="xx-small">
<li>Capability URL</li>
<ul>
<li>Short lived URL generated for a specific purpose</li>
<li>For example, an user e-mail verification</li>
</ul>
<li>URI Alias</li>
<ul>
<li>Two different URIs identifying the same resource</li>
</ul>
<li>URI Collision</li>
<ul>
<li>One URI identifying two different resources (misuse of an URI authority)</li>
</ul>
<li>URI Opacity</li>
<ul>
<li>Content type encoded as part of an URI</li>
<li><code>http://www.example.org/customers.xml</code>
</ul>
<li>Resource versions encoded in an URI</li>
<ul>
<li>Two URIs identifying the same resource of different versions</li>
<li><code>http://www.example.org/v1/customers.xml</code>
</ul>
<li>Persistent URL</li>
<ul>
<li>URL is valid even when the resource is obsolete</li>
<li>For example, a redirection should be in place</li>
</ul>
</ul>
</div>
</section>
<div class="slide outline"></div>
<section>
<header>Resource Representation</header>
<div class="slide">
<hgroup>
<h1>Representation and Data Format</h1>
</hgroup>
<ul class="small">
<li>Representation</li>
<ul>
<li>Various languages, one resource can have multiple representations</li>
<ul>
<li>XML, HTML, JSON, YAML, RDF, ...</li>
<li>should conform to Internet Media Types</li>
</ul>
</ul>
<li>Data format</li>
<ul>
<li>Format of resource data</li>
<li>Binary format</li>
<ul>
<li>specific data structures</li>
<li>pointers, numeric values, compressed, etc.</li>
</ul>
<li>Textual format</li>
<ul>
<li>in a defined encoding as a sequence of characters</li>
<li>HTML, XML-based formats are textual</li>
</ul>
</ul>
</ul>
</div>
<div class="slide">
<hgroup>
<h1>Metadata</h1>
</hgroup>
<ul class="x-small">
<li>Metadata ~ self-description</li>
<ul>
<li>Data about the resource</li>
<li>e.g., data format, representation, date the resource was created, ...</li>
<li class="space-before no-bullet">1. Defined by HTTP response headers</li>
<li class="no-bullet">2. Can be part of the data format</li>
<ul>
<li>Atom Syndication Format such as <code>author</code>, <code>updated</code>, ...</li>
<li>HTML <code>http-equiv</code> meta tags</li>
</ul>
</ul>
<li>Resource anatomy</li>
<img src="img/resource-anatomy.png" style="padding-left: 130px" width="460px" />
</ul>
</div>
<div class="slide">
<hgroup>
<h1>Content-Type Metadata</h1>
</hgroup>
<ul class="x-small">
<li>Access</li>
<ul>
<li>to be retrieved (GET)</li>
<li>to be inserted or updated (PUT, POST)</li>
<li>to be deleted (DELETE)</li>
</ul>
<li>Request</li>
<ul>
<li>HTTP header <code>Accept</code>, part of content negotiation protocol</li>
</ul>
<li>Response</li>
<ul>
<li>HTTP header <code>Content-Type: type/subtype; parameters</code></li>
<li>Specifies an <span id="rfc-2045" class="h-ref">Internet
Media Type</span> of the resource representation.</li>
<ul>
<li>IANA (Internet Assigned Numbers Authority)
manages a <span id="iana-media-types" class="h-ref">registry of media types</span> and character encodings
</li>
<li>subtypes of <code>text</code> type have an optional charset parameter<br />
<code>text/html; charset=iso-8859-1</code>
</li>
</ul>
<li>A resource may provide more than one representations</li>
<ul>
<li>promotes services' loose coupling</li>
</ul>
</ul>
</ul>
</div>
<div class="slide">
<hgroup>
<h1>Major Media Types</h1>
</hgroup>
<ul class="small">
<li>Common Standard Media Types</li>
<ul>
<li><code>text/plain</code></li>
<ul>
<li>natural text in no formal structures</li>
</ul>
<li><code>text/html</code></li>
<ul>
<li>natural text embedded in HTML format</li>
</ul>
<li><code>application/xml</code>, <code>application/json</code></li>
<ul>
<li>XML-based/JSON-based, application specific format</li>
</ul>
<li><code>application/wsdl+xml</code></li>
<ul>
<li><code>+xml</code> suffix to indicate a specific format</li>
</ul>
</ul>
<li>Non-standard media types</li>
<ul>
<li>Types or subtypes that begin with <code>x-</code> are not in IANA<br />
<code>application/x-latex</code>
</li>
<li>subtypes that begin with <code>vnd.</code> are vendor-specific<br />
<code>application/vnd.ms-excel</code>
</li>
</ul>
</ul>
</div>
<div class="slide">
<hgroup>
<h1>Resource State</h1>
</hgroup>
<ul class="x-small">
<li>State</li>
<ul>
<li>Resource representation is in fact a <b>representation of a resource state</b></li>
<li>Resource may be in different states over time</li>
</ul>
</ul>
<div class="h-drawing" style="height: 250px; margin: 15px 0px 15px 0px;"
id="1dhjNo4p6x5rS-IH3E2WcVw3TxwCqmdhtA-9wD0hwbuc"></div>
<ul class="small space-before">
<li>In REST resource states represent application states</li>
</ul>
</div>
<div class="slide" id="resource-state">
<hgroup>
<h1>Resource State Example</h1>
</hgroup>
<ul class="x-small">
<li>Time <code>t1</code>: client A retrieves a resource <code>/orders</code> (GET)</li>
<pre class="brush: xml; class-name: 'tight'">
<orders>
<order id="54467"/>
<order id="65432"/>
</orders>
</pre>
<li>Time <code>t2</code>: client B adds a new order (POST)</li>
<pre class="brush: xml; class-name: 'tight'">
<order>
...
</order>
</pre>
<li>Time <code>t3</code>: client A retrieves a resource <code>/orders</code> (GET)</li>
<pre class="brush: xml; class-name: 'tight'">
<orders>
<order id="54467"/>
<order id="65432"/>
<order id="74567"/>
</orders>
</pre>
<li>The resource <code>/orders</code> has different states in <code>t1</code>
and <code>t3</code>.
</ul>
</div>
</section>
<div class="slide outline"></div>
<section>
<header>Uniform Interface</header>
<div class="slide">
<hgroup>
<h1>Uniform Interface</h1>
</hgroup>
<ul class="small">
<li>Uniform interface = finite set of operations</li>
<ul>
<li>Resource manipulation</li>
<ul>
<li>CRUD – Create (POST/PUT), Read (GET), Update (PUT/PATCH), Delete (DELETE)</li>
</ul>
<li>operations are not domain-specific</li>
<ul>
<li>For example, <code>GET /orders</code> and not <code>getOrders()</code></li>
<li>This reduces complexity when solving interoperability</li>
</ul>
</ul>
<li>Integration issues examples</li>
</ul>
<img src="img/integration-issues.png" style="padding-left: 50px" width="700px" />
</div>
<div class="slide">
<hgroup>
<h1>Safe and Unsafe Operations</h1>
</hgroup>
<ul class="small">
<li>Safe operations</li>
<ul>
<li>Do not change the resource state</li>
<li>Usually "read-only" or "lookup" operation</li>
<li>Clients can cache the results and refresh the cache freely</li>
</ul>
<li>Unsafe operations</li>
<ul>
<li>May change the state of the resource</li>
<li>Transactions such as buy a ticket, post a message</li>
<li>Unsafe does not mean dangerous!</li>
</ul>
<li>Unsafe interactions and transaction results</li>
<ul>
<li><code>POST</code> response may include transaction results</li>
<ul>
<li>you buy a ticket and submit a purchase data</li>
<li>you get transaction results</li>
<li>and you cannot bookmark this..., why?</li>
</ul>
<li>Should be referable with a persistent URI</li>
</ul>
</ul>
</div>
<div class="slide">
<hgroup>
<h1>Idempotence</h1>
</hgroup>
<ul>
<li>Idempotent operation</li>
<ul>
<li>Invoking a method on the same resource always has the same effect</li>
<li>Operations <code>GET</code>, <code>PUT</code>, <code>DELETE</code></li>
</ul>
<li>Non-idempotent operation</li>
<ul>
<li>Invoking a method on the same resource may have different effects</li>
<li>Operation <code>POST</code></li>
</ul>
<li>Effect = a state change</li>
<ul>
<li>recall the effect definition in MDW</li>
</ul>
</ul>
</div>
<div class="slide">
<hgroup>
<h1>GET</h1>
</hgroup>
<ul class="small">
<li>Reading</li>
<ul>
<li><code>GET</code> retrieves a representation of a state of a resource</li>
<pre class="brush: plain; gutter: 'false'">
> GET /orders HTTP/1.1
> Accept: application/xml
< HTTP/1.1 200 OK
< Content-Type: application/xml
<
< ...resource representation in xml...
</pre>
<li>It is read-only operation</li>
<li>It is <b>safe</b></li>
<li>It is <b>idempotent</b></li>
<li class="space-before"><code>GET</code> retrieves different states over time but
the effect is always the same, cf.
<a href="lecture2.html#/resource-state">resource state</a> hence it is idempotent.
</li>
<li>Invocation of <code>GET</code> involves content negotiation</li>
</ul>
</ul>
</div>
<div class="slide" id="PUT">
<hgroup>
<h1>PUT</h1>
</hgroup>
<ul class="small">
<li>Updating or Inserting</li>
<ul>
<li><code>PUT</code> updates or inserts a representation of a state of a resource</li>
<li>Updating the resource is a <b>complete replacement of the resource</b></li>
<pre class="brush: xml; gutter: 'false'">
> PUT /orders/4456 HTTP/1.1
> Content-Type: application/xml
>
> <order>...</order>
< HTTP/1.1 CODE
</pre>
<li>where CODE is:</li>
<ul>
<li><code>200 OK</code> or <code>204 No Content</code> for updating:
A resource with id <code>4456</code> <b>exists</b>, the client
sends an updated resource</li>
<li><code>201 Created</code> for inserting: A resource <b>does not exist</b>, the client
generates the id <code>4456</code> and sends a representation of it.</li>
</ul>
<li>It is <b>not safe</b> and it is <b>idempotent</b></li>
</ul>
</ul>
</div>
<div class="slide">
<hgroup>
<h1>PATCH</h1>
</hgroup>
<ul class="x-small">
<li><code>PATCH</code> to partial update a resource</li>
<ul>
<li>IETF specification, see <span id="rfc-5789" class="h-ref"></span></li>
</ul>
<li>Use in GData Protocol</li>
<ul>
<li>To add, modify or delete selected elements of an Atom feed entry</li>
<li>Example to delete a description element and add a new title element
<br /><code>gd:fields</code> uses the partial response syntax
</li>
<pre class="brush: xml; class-name: 'tight'">
PATCH /myFeed/1/1/
Content-Type: application/xml
<entry xmlns='http://www.w3.org/2005/Atom'
xmlns:gd='http://schemas.google.com/g/2005'
gd:fields='description'>
<title>New title</title>
</entry></pre>
<li>Rules</li>
<ul>
<li>Fields not already present are added</li>
<li>Non-repeating fields already present are updated</li>
<li>Repeating fields already present are appended</li>
</ul>
</ul>
</ul>
</div>
<div class="slide">
<hgroup>
<h1>POST</h1>
</hgroup>
<ul class="small">
<li>Inserting</li>
<ul>
<li><code>POST</code> inserts a new resource</li>
<li>A server generates a new resource ID, client only supplies a content and a resource URI where the new
resource will be inserted.</li>
<pre class="brush: xml; gutter: 'false'">
> POST /orders HTTP/1.1
> Content-Type: application/xml
>
> <order>...</order>
< HTTP/1.1 201 Created
< Location: /orders/4456
</pre>
<li>It is <b>not safe</b> an it is <b>not idempotent</b><br />
<li class="space-before">A client may "suggest" a resource's id using the <code>Slug</code> header</li>
<ul>
<li>Defined in <span class="h-ref" id="rfc-5023">AtomPub protocol</span></li>
</ul>
</ul>
</ul>
</div>
<div class="slide">
<hgroup>
<h1>DELETE</h1>
</hgroup>
<ul class="small">
<li>Deleting</li>
<ul>
<li><code>DELETE</code> deletes a resource with specified URI</li>
<pre class="brush: plain; gutter: 'false'">
> DELETE /orders/4456 HTTP/1.1
< HTTP/1.1 CODE
</pre>
<li>where CODE is:</li>
<ul>
<li><code>200 OK</code>: the response body contains an entity describing a result of the operation.</li>
<li><code>204 No Content</code>: there is no response body.</li>
</ul>
<li class="space-before">It is <b>not safe</b> and it is <b>idempotent</b></li>
<ul>
<li>Multiple invocation of <code>DELETE /orders/4456</code> has always the same effect – the resource
<code>/orders/4456</code> does not exist.
</li>
</ul>
</ul>
</ul>
</div>
<div class="slide">
<hgroup>
<h1>Other</h1>
</hgroup>
<ul class="small">
<li>HEAD</li>
<ul>
<li>same as <code>GET</code> but only retrieves HTTP headers</li>
<li>It is <b>safe</b> and <b>idempotent</b></li>
</ul>
<li>OPTIONS</li>
<ul>
<li>queries the resource for resource configuration</li>
<li>It is <b>safe</b> and <b>idempotent</b></li>
</ul>
</ul>
</div>
<div class="slide">
<hgroup>
<h1>Types of Errors</h1>
</hgroup>
<ul class="x-small">
<li>Client-side – status code <code>4xx</code></li>
<ul>
<li><code>400 Bad Request</code></li>
<ul>
<li>generic client-side error</li>
<li>invalid format, such as syntax or validation error</li>
</ul>
<li><code>404 Not Found</code></li>
<ul>
<li>server can't map URI to a resource</li>
</ul>
<li><code>401 Unauthorized</code></li>
<ul>
<li>wrong credentials (such as user/pass, or API key)</li>
<li>the response contains <code>WWW-Authenticate</code> indicating what kind of authentication
the service accepts</li>
</ul>
<li><code>405 Method Not Allowed</code></li>
<ul>
<li>the resource does not support the HTTP method the client used</li>
<li>the response contains <code>Allow</code> header to indicate methods it supports</li>
</ul>
<li><code>406 Not Acceptable</code></li>
<ul>
<li>so many restrictions on acceptable content types (using <code>Accept-*</code>)</li>
<li>server cannot serialize the resource to requested content types</li>
</ul>
</ul>
</ul>
</div>
<div class="slide">
<hgroup>
<h1>Types of Errors (Cont.)</h1>
</hgroup>
<ul class="x-small">
<li>Server-side – status code <code>5xx</code></li>
<ul>
<li><code>500 Internal Server Error</code></li>
<ul>
<li>generic server-side error</li>
<li>usually not expressive, logs a message for system admins</li>
</ul>
<li><code>503 Service Not Available</code></li>
<ul>
<li>server is overloaded or is under maintenance</li>
<li>the response contains <code>Retry-After</code> header</li>
</ul>
</ul>
</ul>
</div>
<div class="slide">
<hgroup>
<h1>Use of Status Codes</h1>
</hgroup>
<ul class="small">
<li>Service should respect semantics of status codes!</li>
<ul>
<pre class="brush: js; gutter: 'false''">
> GET /orders HTTP/1.1
> Accept: application/json
< HTTP/1.1 200 OK
< Content-Type: application/json
<
< { "error" :
< { "error_text" :
< "you do not have rights to access this resource " }
< }
</pre>
<li>Client must understand the semantics of the response.</li>
<li>This breaks loose coupling and reusability service principles</li>
<li>The response should be:</li>
<pre class="brush: plain; gutter: 'false'">
< HTTP/1.1 401 Unauthorized
< ...
< ...optional text describing the error...
</pre>
</ul>
</ul>
</div>
<div class="slide">
<hgroup>
<h1>Respect HTTP Semantics</h1>
</hgroup>
<ul class="small">
<li>Do not overload semantics of HTTP methods</li>
<ul>
<li>For example, <code>GET</code> is read-only method and idempotent</li>
<li>REST Anti-pattern:</li>
<li class="no-bullet"> <code>GET /orders/?add=new_order</code></li>
<ul>
<li>This is not REST!</li>
<li>This breaks both safe and idempotent principles</li>