RESTful Web Services

A textbook introduction to RESTful Web Services, the Web and the HTTP protocol. There has been a lot of hype about REST lately, but very few people understand how to implement RESTful Web Services correctly and how the Web actually works. Presented at ThoughtWorks.

1. a n i n t r o d u c t i o n t o RESTFUL WEB SERVICES Felipe Dornelas
2. AGENDA 2 ▫︎The Internet ▫︎The Web and its Resources ▫︎HTTP ▫︎The Resource-Oriented Architecture ▫︎RESTful Web Services
3. WHAT IS REST? 3 HTTP + Resource-Oriented Architecture
4. THE INTERNET A network of networks 4
7. THE INTERNET, 2010 7
8. INTERNET ROUTES 8
9. INTERNET ROUTES 9
10. CACHING 10
11. INTERNET LAYERS 11 Web, E-mail, BitTorrent, DNS… TCP, UDP… Internet Protocol (IP) WiFi, Ethernet, 3G, LTE…
12. INTERNET LAYERS 12 We will talk about the Web
13. THE WEB An application of the Internet 13
14. WHAT IS THE WEB? 14 An information system of interlinked hypertext documents and resources accessed via the Internet
15. HYPERTEXT DOCUMENTS 15
16. HYPERTEXT MARKUP LANGUAGE 16 <!doctype html> <html> <head> <title>Example Hypertext Document</title> </head> <body> <div> <h1>Example Hypertext Document</h1> <p>This is an example hypertext document to be used for illustrative purposes.</p> <p><a href=“http://example.org”> Example Hyperlink</a></p> </div> </body> </html>
17. HYPERTEXT TRANSFER PROTOCOL 17 Server Client example.com Mozilla Firefox
18. HYPERTEXT TRANSFER PROTOCOL 18 Server Client HTTP Request example.com Mozilla Firefox
19. HTTP REQUEST 19 GET / HTTP/1.1 User-Agent: Mozilla Firefox Host: example.com Accept: */*
20. HYPERTEXT TRANSFER PROTOCOL 20 Server Client HTTP Response example.com Mozilla Firefox
21. HTTP RESPONSE 21 HTTP/1.1 200 OK Content-Type: text/html Content-Length: 1270 <!doctype html> <html> <head> <title>Example Domain</title> </head> <body> … </body> </html>
23. INTERNET LAYERS 23 HTTP TCP Internet Protocol (IP) WiFi, Ethernet, 3G, LTE…
24. RESOURCES 24 Anything that can be identified, named, addressed or handled on the Web
25. RESOURCES 25 ▫︎Can be concrete things: ▫︎Web pages ▫︎Files ▫︎Videos ▫︎Blog posts ▫︎Articles
26. RESOURCES 26 ▫︎Can also represent abstract concepts: ▫︎Employees in a enterprise ▫︎Money transfers ▫︎Products in a online store ▫︎Calendar appointments ▫︎User accounts
27. RESOURCE NAMES 27 ▫︎URN - Uniform Resource Name ▫︎products/54321 ▫︎about-us ▫︎articles/web.html ▫︎posts/2015-04-13 ▫︎podcasts/rest.mp3
28. RESOURCE LOCATORS 28 ▫︎URL - Uniform Resource Locator ▫︎http://example.com/products/54321 ▫︎http://example.com/about-us ▫︎http://example.com/articles/web.html ▫︎http://example.com/posts/2015-04-13 ▫︎http://example.com/podcasts/rest.mp3
29. ANATOMY OF AN URL 29
30. RESOURCE IDENTIFIERS 30
31. RESOURCE IDENTIFIERS 31 A resource only exists on the Web if it has an identifier (URI)
32. RESOURCES 32 HTTP can manipulate not only hypertext documents but any type of resources
33. Imaginary HTTP server: example.com 33
34. READING A TEXT RESOURCE 34 http://example.com/hello-world.txt
35. READING A TEXT RESOURCE 35 GET /hello-world.txt HTTP/1.1 Host: example.com HTTP Request
36. READING A TEXT RESOURCE 36 HTTP/1.1 200 OK Content-Type: text/plain Content-Length: 13 Hello, World! HTTP Response
37. CREATING A TEXT RESOURCE 37 POST / HTTP/1.1 Host: example.com Content-Type: text/plain Hello, Mars! HTTP Request
38. CREATING A TEXT RESOURCE 38 HTTP/1.1 201 Created Location: /hello-mars.txt HTTP Response
39. CREATING A TEXT RESOURCE 39 http://example.com/hello-mars.txt
40. RESOURCE DOES NOT EXIST 40 http://example.com/hello-pluto.txt
41. RESOURCE DOES NOT EXIST 41 GET /hello-pluto.txt HTTP/1.1 Host: example.com HTTP Request
42. RESOURCE DOES NOT EXIST 42 HTTP/1.1 404 Not Found HTTP Response
43. HTTP CONTENT TYPES 43 ▫︎Determine the type of the HTTP payload ▫︎text/html - HTML ▫︎text/plain - Plain Text ▫︎audio/mpeg3 - MP3 files ▫︎application/xml - XML ▫︎…
44. HTTP VERBS 44 ▫︎GET ▫︎POST ▫︎PUT ▫︎DELETE ▫︎HEAD ▫︎OPTIONS
45. HTTP STATUS CODES 45 ▫︎Success (2xx) ▫︎200 OK ▫︎201 Created ▫︎204 No Content ▫︎…
46. HTTP STATUS CODES 46 ▫︎Client Error (4xx) ▫︎400 Bad Request ▫︎404 Not Found ▫︎409 Conflict ▫︎…
47. HTTP STATUS CODES 47 ▫︎Server Error (5xx) ▫︎500 Internal Server Error ▫︎503 Server Unavailable ▫︎…
48. THE RESOURCE-ORIENTED ARCHITECTURE 48
49. REST 49 Representational State Transfer
50. REST 50 HTTP + Resource-Oriented Architecture
51. REST 51 HTTP + Resource-Oriented Architecture RESTful
52. EMPLOYEE RESOURCE 52
53. EMPLOYEE RESOURCE 53 ▫︎Alice ▫︎Developer ▫︎Female ▫︎…
54. XML REPRESENTATION 54 <employee> <name>Alice</name> <role>Developer</role> <gender>female</gender> </employee>
55. JSON REPRESENTATION 55 { "name": "Alice", "role": "Developer", "gender": "female" }
56. HTML REPRESENTATION 56 <h1>Alice</h1> <dl> <dt>Role:</dt> <dd>Developer</dd> <dt>Gender:</dt> <dd>Female</dd> </dl>
57. EMPLOYEE RESOURCE 57 /employees
58. EMPLOYEE RESOURCE 58 /employees/alice /employees/bob /employees/eve
59. RESOURCE OPERATIONS 59 ▫︎Create ▫︎Read ▫︎Update ▫︎Delete ▫︎List
60. LIST EMPLOYEE RESOURCES 60 GET /employees HTTP/1.1 Host: example.com Accept: application/xml HTTP Request
61. LIST EMPLOYEE RESOURCES 61 HTTP/1.1 200 OK Content-Type: application/xml <employees> <employee href="/employees/alice"/> <employee href="/employees/bob"/> <employee href="/employees/eve"/> </employee> HTTP Response
62. READ EMPLOYEE RESOURCE 62 GET /employees/alice HTTP/1.1 Host: example.com Accept: application/xml HTTP Request
63. READ EMPLOYEE RESOURCE 63 HTTP/1.1 200 OK Content-Type: application/xml <employee> <name>Alice</name> <role>Developer</role> <gender>female</gender> </employee> HTTP Response
64. CREATE EMPLOYEE RESOURCE 64 POST /employees HTTP/1.1 Host: example.com Content-Type: application/xml <employee> <name>John</name> <role>QA</role> <gender>male</gender> </employee> HTTP Request
65. CREATE EMPLOYEE RESOURCE 65 HTTP/1.1 201 Created Location: /employees/john HTTP Response
66. UPDATE EMPLOYEE RESOURCE 66 PUT /employees/alice HTTP/1.1 Host: example.com Content-Type: application/xml <employee> <name>Alice</name> <role>Manager</role> <gender>female</gender> </employee> HTTP Request
67. UPDATE EMPLOYEE RESOURCE 67 HTTP/1.1 200 OK HTTP Response
68. DELETE EMPLOYEE RESOURCE 68 DELETE /employees/alice HTTP/1.1 Host: example.com HTTP Request
69. DELETE EMPLOYEE RESOURCE 69 HTTP/1.1 204 No Content HTTP Response
70. RESOURCE-ORIENTED ARCHITECTURE 70 1. Addressability 2. Statelessness 3. Connectedness 4. Uniform Interface
71. ADDRESSABILITY 71 Every interesting piece of information the server can provide should be exposed as a resource, and given its own URI
72. ADDRESSABILITY 72 http://example.com/employees/alice
73. STATELESSNESS 73 Every HTTP request should happen in complete isolation
74. STATELESSNESS 74 http://google.com/search?q=jellyfish
75. STATELESSNESS 75
76. STATELESSNESS 76
77. STATELESSNESS 77 http://google.com/search? q=jellyfish&start=10
78. STATELESSNESS 78 Application State vs. Resource State
79. CONNECTEDNESS 79 Documents should contain not just data, but links to other resources
80. CONNECTEDNESS 80
81. CONNECTEDNESS 81
82. CONNECTEDNESS 82
83. CONNECTEDNESS 83 { "employees": [ "/employees/alice", "/employees/bob", "/employees/eve", ... ] "next_page": "/employees?start=10", "create_employee": "/employees" }
84. HATEOAS 84 Hypermedia As The Engine of Application State
85. UNIFORM INTERFACE 85 ▫︎Create: POST /employees ▫︎Read: GET /employees/alice ▫︎Update: PUT /employees/alice ▫︎Delete: DELETE /employees/alice ▫︎List: GET /employees
86. UNIFORM INTERFACE 86 ▫︎Create: POST /resource ▫︎Read: GET /resource/{name} ▫︎Update: PUT /resource/{name} ▫︎Delete: DELETE /resource/{name} ▫︎List: GET /resource
87. SAFETY 87 GET and HEAD never change the resource state
88. INDEMPOTENCE 88 PUT and DELETE are indempotent
89. RESTFUL WEB SERVICES 89
90. WEB SERVICES 90 client server Web
91. BIG WEB SERVICES 91 ▫︎Heavy ▫︎Don’t scale ▫︎Hard to understand ▫︎Tight coupling ▫︎SOAP, WSDL, etc…
92. TIGHT COUPLING 92
93. BROKEN TIGHT COUPLING 93
94. RESTFUL WEB SERVICES 94 ▫︎Lightweight ▫︎Cacheable ▫︎Scalable ▫︎Discoverable ▫︎Loose coupling
95. RESOURCE-ORIENTED ARCHITECTURE 95 1. Addressability 2. Statelessness 3. Connectedness 4. Uniform Interface
96. CACHEABILITY 96 GET http://example.com/employees/alice
97. CACHEABILITY 97 GET http://example.com/employees/alice
98. SCALABILITY 98 GET http://example.com/employees/alice client server
99. SCALABILITY 99 GET http://example.com/employees/alice client server cluster
100. DISCOVERABILITY 100
101. DISCOVERABILITY 101 { "employees": [ "/employees/alice", "/employees/bob", "/employees/eve", ... ] "next_page": "/employees?start=10", "create_employee": "/employees" }
102. PUBLIC RESTFUL APIS 102 ▫︎Twitter ▫︎GitHub ▫︎Amazon S3
103. REFERENCE 103 RESTful Web Services Leonard Richardson Sam Ruby
104. Felipe Dornelas fdornelas@thoughtworks.com THANK YOU