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.

Transcript

1. a n i n t r o d u c t i o n t o
   RESTFUL WEB SERVICES
   Felipe Dornelas
   

   View Slide

2. AGENDA
   2
   ▫︎The Internet
   ▫︎The Web and its Resources
   ▫︎HTTP
   ▫︎The Resource-Oriented Architecture
   ▫︎RESTful Web Services
   

   View Slide

3. WHAT IS REST?
   3
   HTTP + Resource-Oriented Architecture
   

   View Slide

4. THE INTERNET
   A network of networks
   4
   

   View Slide

5. View Slide

6. View Slide

7. THE INTERNET, 2010
   7
   

   View Slide

8. INTERNET ROUTES
   8
   

   View Slide

9. INTERNET ROUTES
   9
   

   View Slide

10. CACHING
    10
    

    View Slide

11. INTERNET LAYERS
    11
    Web, E-mail, BitTorrent, DNS…
    TCP, UDP…
    Internet Protocol (IP)
    WiFi, Ethernet, 3G, LTE…
    

    View Slide

12. INTERNET LAYERS
    12
    We will talk about
    the Web
    

    View Slide

13. THE WEB
    An application of the Internet
    13
    

    View Slide

14. WHAT IS THE WEB?
    14
    An information system of interlinked
    hypertext documents and resources
    accessed via the Internet
    

    View Slide

15. HYPERTEXT DOCUMENTS
    15
    

    View Slide

16. HYPERTEXT MARKUP LANGUAGE
    16
    
    
    
    Example Hypertext Document
    
    
    
    Example Hypertext Document
    This is an example hypertext document to be
    used for illustrative purposes.
    
    Example Hyperlink
    
    
    
    

    View Slide

17. HYPERTEXT TRANSFER PROTOCOL
    17
    Server
    Client
    example.com
    Mozilla Firefox
    

    View Slide

18. HYPERTEXT TRANSFER PROTOCOL
    18
    Server
    Client
    HTTP Request
    example.com
    Mozilla Firefox
    

    View Slide

19. HTTP REQUEST
    19
    GET / HTTP/1.1
    User-Agent: Mozilla Firefox
    Host: example.com
    Accept: */*
    

    View Slide

20. HYPERTEXT TRANSFER PROTOCOL
    20
    Server
    Client
    HTTP Response
    example.com
    Mozilla Firefox
    

    View Slide

21. HTTP RESPONSE
    21
    HTTP/1.1 200 OK
    Content-Type: text/html
    Content-Length: 1270
    
    
    
    Example Domain
    
    …
    
    

    View Slide

22. View Slide

23. INTERNET LAYERS
    23
    HTTP
    TCP
    Internet Protocol (IP)
    WiFi, Ethernet, 3G, LTE…
    

    View Slide

24. RESOURCES
    24
    Anything that can be identified, named,
    addressed or handled on the Web
    

    View Slide

25. RESOURCES
    25
    ▫︎Can be concrete things:
    ▫︎Web pages
    ▫︎Files
    ▫︎Videos
    ▫︎Blog posts
    ▫︎Articles
    

    View Slide

26. RESOURCES
    26
    ▫︎Can also represent abstract concepts:
    ▫︎Employees in a enterprise
    ▫︎Money transfers
    ▫︎Products in a online store
    ▫︎Calendar appointments
    ▫︎User accounts
    

    View Slide

27. RESOURCE NAMES
    27
    ▫︎URN - Uniform Resource Name
    ▫︎products/54321
    ▫︎about-us
    ▫︎articles/web.html
    ▫︎posts/2015-04-13
    ▫︎podcasts/rest.mp3
    

    View Slide

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
    

    View Slide

29. ANATOMY OF AN URL
    29
    

    View Slide

30. RESOURCE IDENTIFIERS
    30
    

    View Slide

31. RESOURCE IDENTIFIERS
    31
    A resource only exists on the Web if it has an
    identifier (URI)
    

    View Slide

32. RESOURCES
    32
    HTTP can manipulate not only hypertext
    documents but any type of resources
    

    View Slide

33. Imaginary HTTP server:
    example.com
    33
    

    View Slide

34. READING A TEXT RESOURCE
    34
    http://example.com/hello-world.txt
    

    View Slide

35. READING A TEXT RESOURCE
    35
    GET /hello-world.txt HTTP/1.1
    Host: example.com
    HTTP Request
    

    View Slide

36. READING A TEXT RESOURCE
    36
    HTTP/1.1 200 OK
    Content-Type: text/plain
    Content-Length: 13
    Hello, World!
    HTTP Response
    

    View Slide

37. CREATING A TEXT RESOURCE
    37
    POST / HTTP/1.1
    Host: example.com
    Content-Type: text/plain
    Hello, Mars!
    HTTP Request
    

    View Slide

38. CREATING A TEXT RESOURCE
    38
    HTTP/1.1 201 Created
    Location: /hello-mars.txt
    HTTP Response
    

    View Slide

39. CREATING A TEXT RESOURCE
    39
    http://example.com/hello-mars.txt
    

    View Slide

40. RESOURCE DOES NOT EXIST
    40
    http://example.com/hello-pluto.txt
    

    View Slide

41. RESOURCE DOES NOT EXIST
    41
    GET /hello-pluto.txt HTTP/1.1
    Host: example.com
    HTTP Request
    

    View Slide

42. RESOURCE DOES NOT EXIST
    42
    HTTP/1.1 404 Not Found
    HTTP Response
    

    View Slide

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
    ▫︎…
    

    View Slide

44. HTTP VERBS
    44
    ▫︎GET
    ▫︎POST
    ▫︎PUT
    ▫︎DELETE
    ▫︎HEAD
    ▫︎OPTIONS
    

    View Slide

45. HTTP STATUS CODES
    45
    ▫︎Success (2xx)
    ▫︎200 OK
    ▫︎201 Created
    ▫︎204 No Content
    ▫︎…
    

    View Slide

46. HTTP STATUS CODES
    46
    ▫︎Client Error (4xx)
    ▫︎400 Bad Request
    ▫︎404 Not Found
    ▫︎409 Conflict
    ▫︎…
    

    View Slide

47. HTTP STATUS CODES
    47
    ▫︎Server Error (5xx)
    ▫︎500 Internal Server Error
    ▫︎503 Server Unavailable
    ▫︎…
    

    View Slide

48. THE
    RESOURCE-ORIENTED
    ARCHITECTURE
    48
    

    View Slide

49. REST
    49
    Representational State Transfer
    

    View Slide

50. REST
    50
    HTTP + Resource-Oriented Architecture
    

    View Slide

51. REST
    51
    HTTP + Resource-Oriented Architecture
    RESTful
    

    View Slide

52. EMPLOYEE RESOURCE
    52
    

    View Slide

53. EMPLOYEE RESOURCE
    53
    ▫︎Alice
    ▫︎Developer
    ▫︎Female
    ▫︎…
    

    View Slide

54. XML REPRESENTATION
    54
    
    Alice
    Developer
    female
    
    

    View Slide

55. JSON REPRESENTATION
    55
    {
    "name": "Alice",
    "role": "Developer",
    "gender": "female"
    }
    

    View Slide

56. HTML REPRESENTATION
    56
    Alice
    
    Role:
    Developer
    Gender:
    Female
    
    

    View Slide

57. EMPLOYEE RESOURCE
    57
    /employees
    

    View Slide

58. EMPLOYEE RESOURCE
    58
    /employees/alice
    /employees/bob
    /employees/eve
    

    View Slide

59. RESOURCE OPERATIONS
    59
    ▫︎Create
    ▫︎Read
    ▫︎Update
    ▫︎Delete
    ▫︎List
    

    View Slide

60. LIST EMPLOYEE RESOURCES
    60
    GET /employees HTTP/1.1
    Host: example.com
    Accept: application/xml
    HTTP Request
    

    View Slide

61. LIST EMPLOYEE RESOURCES
    61
    HTTP/1.1 200 OK
    Content-Type: application/xml
    
    
    
    
    
    HTTP Response
    

    View Slide

62. READ EMPLOYEE RESOURCE
    62
    GET /employees/alice HTTP/1.1
    Host: example.com
    Accept: application/xml
    HTTP Request
    

    View Slide

63. READ EMPLOYEE RESOURCE
    63
    HTTP/1.1 200 OK
    Content-Type: application/xml
    
    Alice
    Developer
    female
    
    HTTP Response
    

    View Slide

64. CREATE EMPLOYEE RESOURCE
    64
    POST /employees HTTP/1.1
    Host: example.com
    Content-Type: application/xml
    
    John
    QA
    male
    
    HTTP Request
    

    View Slide

65. CREATE EMPLOYEE RESOURCE
    65
    HTTP/1.1 201 Created
    Location: /employees/john
    HTTP Response
    

    View Slide

66. UPDATE EMPLOYEE RESOURCE
    66
    PUT /employees/alice HTTP/1.1
    Host: example.com
    Content-Type: application/xml
    
    Alice
    Manager
    female
    
    HTTP Request
    

    View Slide

67. UPDATE EMPLOYEE RESOURCE
    67
    HTTP/1.1 200 OK
    HTTP Response
    

    View Slide

68. DELETE EMPLOYEE RESOURCE
    68
    DELETE /employees/alice HTTP/1.1
    Host: example.com
    HTTP Request
    

    View Slide

69. DELETE EMPLOYEE RESOURCE
    69
    HTTP/1.1 204 No Content
    HTTP Response
    

    View Slide

70. RESOURCE-ORIENTED ARCHITECTURE
    70
    1. Addressability
    2. Statelessness
    3. Connectedness
    4. Uniform Interface
    

    View Slide

71. ADDRESSABILITY
    71
    Every interesting piece of information the server
    can provide should be exposed as a resource,
    and given its own URI
    

    View Slide

72. ADDRESSABILITY
    72
    http://example.com/employees/alice
    

    View Slide

73. STATELESSNESS
    73
    Every HTTP request should happen in
    complete isolation
    

    View Slide

74. STATELESSNESS
    74
    http://google.com/search?q=jellyfish
    

    View Slide

75. STATELESSNESS
    75
    

    View Slide

76. STATELESSNESS
    76
    

    View Slide

77. STATELESSNESS
    77
    http://google.com/search?
    q=jellyfish&start=10
    

    View Slide

78. STATELESSNESS
    78
    Application State vs. Resource State
    

    View Slide

79. CONNECTEDNESS
    79
    Documents should contain not just data,
    but links to other resources
    

    View Slide

80. CONNECTEDNESS
    80
    

    View Slide

81. CONNECTEDNESS
    81
    

    View Slide

82. CONNECTEDNESS
    82
    

    View Slide

83. CONNECTEDNESS
    83
    {
    "employees": [
    "/employees/alice",
    "/employees/bob",
    "/employees/eve",
    ...
    ]
    "next_page": "/employees?start=10",
    "create_employee": "/employees"
    }
    

    View Slide

84. HATEOAS
    84
    Hypermedia As The Engine of Application State
    

    View Slide

85. UNIFORM INTERFACE
    85
    ▫︎Create: POST /employees
    ▫︎Read: GET /employees/alice
    ▫︎Update: PUT /employees/alice
    ▫︎Delete: DELETE /employees/alice
    ▫︎List: GET /employees
    

    View Slide

86. UNIFORM INTERFACE
    86
    ▫︎Create: POST /resource
    ▫︎Read: GET /resource/{name}
    ▫︎Update: PUT /resource/{name}
    ▫︎Delete: DELETE /resource/{name}
    ▫︎List: GET /resource
    

    View Slide

87. SAFETY
    87
    GET and HEAD never change the resource
    state
    

    View Slide

88. INDEMPOTENCE
    88
    PUT and DELETE are indempotent
    

    View Slide

89. RESTFUL
    WEB SERVICES
    89
    

    View Slide

90. WEB SERVICES
    90
    client
    server
    Web
    

    View Slide

91. BIG WEB SERVICES
    91
    ▫︎Heavy
    ▫︎Don’t scale
    ▫︎Hard to understand
    ▫︎Tight coupling
    ▫︎SOAP, WSDL, etc…
    

    View Slide

92. TIGHT COUPLING
    92
    

    View Slide

93. BROKEN TIGHT COUPLING
    93
    

    View Slide

94. RESTFUL WEB SERVICES
    94
    ▫︎Lightweight
    ▫︎Cacheable
    ▫︎Scalable
    ▫︎Discoverable
    ▫︎Loose coupling
    

    View Slide

95. RESOURCE-ORIENTED ARCHITECTURE
    95
    1. Addressability
    2. Statelessness
    3. Connectedness
    4. Uniform Interface
    

    View Slide

96. CACHEABILITY
    96
    GET http://example.com/employees/alice
    

    View Slide

97. CACHEABILITY
    97
    GET http://example.com/employees/alice
    

    View Slide

98. SCALABILITY
    98
    GET http://example.com/employees/alice
    client
    server
    

    View Slide

99. SCALABILITY
    99
    GET http://example.com/employees/alice
    client
    server cluster
    

    View Slide

100. DISCOVERABILITY
     100
     

     View Slide

101. DISCOVERABILITY
     101
     {
     "employees": [
     "/employees/alice",
     "/employees/bob",
     "/employees/eve",
     ...
     ]
     "next_page": "/employees?start=10",
     "create_employee": "/employees"
     }
     

     View Slide

102. PUBLIC RESTFUL APIS
     102
     ▫︎Twitter
     ▫︎GitHub
     ▫︎Amazon S3
     

     View Slide

103. REFERENCE
     103
     RESTful Web Services
     Leonard Richardson
     Sam Ruby
     

     View Slide

104. Felipe Dornelas
     fdornelas@thoughtworks.com
     THANK YOU
     

     View Slide