HTTP: The Good Parts

REST demands we think about resources, representations, and rich interactions; however, it's easy to forget the substrate upon which our beautiful hypermedia APIs "rest". HTTP has lots of interesting and powerful ways to enhance interaction and efficiency that most applications leave untapped because they focus so much on the act of processing a request, rather than the properties of the resource being requested. Let's look more closely at those HTTP features and then see how you can tap into them more declaratively with Webmachine.

Transcript

1. Sean Cribbs RESTfest 2014 HTTP: The Good Parts
2. HTTP Archaeology
3. HTTP/0.9
4. HTTP/0.9 "The protocol uses the normal internet-style telnet protocol style on a TCP-IP link. The following Describes how a client acquires a (hypertext) document from an HTTP server, given an HTTP document address."
5. HTTP/0.9 "The protocol uses the normal internet-style telnet protocol style on a TCP-IP link. The following Describes how a client acquires a (hypertext) document from an HTTP server, given an HTTP document address." "The client sends a document request consisting of a line of ASCII characters terminated by a CR LF...The response to a simple GET request is a message in hypertext mark-up language ( HTML ). This is a byte stream of ASCII characters."
6. “Basic HTTP”
7. “Basic HTTP” “It is a generic stateless object-oriented protocol, which may be used for many similar tasks such as name servers, and distributed object-oriented systems, by extending the commands, or "methods", used.”
8. “Basic HTTP” “It is a generic stateless object-oriented protocol, which may be used for many similar tasks such as name servers, and distributed object-oriented systems, by extending the commands, or "methods", used.” Media types
9. “Basic HTTP” “It is a generic stateless object-oriented protocol, which may be used for many similar tasks such as name servers, and distributed object-oriented systems, by extending the commands, or "methods", used.” Media types Content Negotiation
10. “Basic HTTP” “It is a generic stateless object-oriented protocol, which may be used for many similar tasks such as name servers, and distributed object-oriented systems, by extending the commands, or "methods", used.” Media types Content Negotiation
11. “Basic HTTP” “It is a generic stateless object-oriented protocol, which may be used for many similar tasks such as name servers, and distributed object-oriented systems, by extending the commands, or "methods", used.” Media types Content Negotiation Conditional requests
12. “Basic HTTP” “It is a generic stateless object-oriented protocol, which may be used for many similar tasks such as name servers, and distributed object-oriented systems, by extending the commands, or "methods", used.” Media types Content Negotiation Conditional requests URI
13. “Basic HTTP” “It is a generic stateless object-oriented protocol, which may be used for many similar tasks such as name servers, and distributed object-oriented systems, by extending the commands, or "methods", used.” Media types Content Negotiation Conditional requests URI Payment, versioning, locking
14. “Basic HTTP” “It is a generic stateless object-oriented protocol, which may be used for many similar tasks such as name servers, and distributed object-oriented systems, by extending the commands, or "methods", used.” Media types Content Negotiation Conditional requests URI Payment, versioning, locking LINK / UNLINK
15. HTTP/1.0 RFC 1945 GET / HEAD / POST 302 Moved Temporarily x-gzip, x-compress Definition of “Safe” methods
16. HTTP/1.1 Entity Tags Cache-Control Informational status codes (1xx) Retry-After Vary Range requests PUT, DELETE, OPTIONS, CONNECT, TRACE
17. REST and HTTP
18. Constraint Promotes At the expense of Client-Server Stateless Optional non-shared Caching Uniform interface Layered system Optional code-on- demand UI Portability Simplified Server Multiple organizational domains Simplified Server Scalability Reliability Efficiency Reduced latency Efficiency Scalability Reliability Visibility Independent evolution Decoupled implementation Efficiency Shared caching Legacy encapsulation Simplified clients Scalability Load balancing Higher latency Simplified clients Extensibility Visibility
19. Constraint Promotes At the expense of Client-Server Stateless Optional non-shared Caching Uniform interface Layered system Optional code-on- demand UI Portability Simplified Server Multiple organizational domains Simplified Server Scalability Reliability Efficiency Reduced latency Efficiency Scalability Reliability Visibility Independent evolution Decoupled implementation Efficiency Shared caching Legacy encapsulation Simplified clients Scalability Load balancing Higher latency Simplified clients Extensibility Visibility •Identification of resources •Manipulation via representations •Self-descriptive messages •HATEOAS
20. Constraint Promotes At the expense of Client-Server Stateless Optional non-shared Caching Uniform interface Layered system Optional code-on- demand UI Portability Simplified Server Multiple organizational domains Simplified Server Scalability Reliability Efficiency Reduced latency Efficiency Scalability Reliability Visibility Independent evolution Decoupled implementation Efficiency Shared caching Legacy encapsulation Simplified clients Scalability Load balancing Higher latency Simplified clients Extensibility Visibility •Identification of resources •Manipulation via representations •Self-descriptive messages •HATEOAS
21. The Bad Parts 1. Verbose and inefficient 2. Ambiguous standard 3. Hard to implement correctly
22. The Good Parts
23. Self-Describing Messaging
24. Interoperability
25. Safeguards
26. Authentication & Authorization
27. Content Negotiation
28. Conditional Requests
29. Caching
30. Redirection & Obsoletion
31. Semantics
32. Client-Server & Statelessness
33. Client-Server & Statelessness Request ! Response
34. State Transfer Request ! Response
35. State Transfer Request ! S ! (Response, S’) Request ! Response
36. State Transfer Request ! S ! (Response, S’) Request ! (S ! (Response, S’)) Request ! Response
37. State Transfer Request ! S ! (Response, S’) Request ! (S ! (Response, S’)) (Request ! S) ! (Response, S’) Request ! Response
38. Request ! (Request ! S) ! (Response, S’) State Transfer Request ! S ! (Response, S’) Request ! (S ! (Response, S’)) Request ! Response
39. Protocol, n. 1. The official procedure governing affairs of state or diplomatic occasions. 2. The established code of procedure or behavior in any group, organization, or situation.
40. FOLLOWING PROTOCOL CORRECT COMMUNICATION MATTERS POOL/REUTERS THE TIMES
41. FINITE STATE MACHINES CSP, SEQUENCE DIAGRAMS, ETC HTTP://WWW.CERCLES.COM/REVIEW/R31/COLEMAN.HTML
42. Function 㱺 FSM
43. Function 㱺 FSM Request ! S ! (Response, S’)
44. Function 㱺 FSM Req ! Res ! S ! (Res', S') Request ! S ! (Response, S’)
45. Extract Req ! Res ! S ! (Res', S')
46. Extract Req ! Res ! S ! (Res', S') Req ! Res ! S ! (V, Res', S')
47. Extract Req ! Res ! S ! (Res', S') Req ! Res ! S ! (V, Res', S') Req ! Res ! V ! Res'
49. Start
50. Start 200 OK
52. validation & auth
53. validation & auth content- negotiation
54. validation & auth content- negotiation existence & redirection
55. validation & auth content- negotiation existence & redirection conditional requests
56. validation & auth content- negotiation existence & redirection conditional requests DELETE
57. validation & auth content- negotiation existence & redirection conditional requests PUT/POST DELETE
58. validation & auth content- negotiation existence & redirection conditional requests PUT/POST DELETE body
59. Resource exists? 404 NOT FOUND REDIRECTION CREATION { 200 OK CONDITION VALIDATION DELETION UPDATE / REPLACE {
60. Resource exists? 404 NOT FOUND REDIRECTION CREATION { 200 OK CONDITION VALIDATION DELETION UPDATE / REPLACE { Req ! Res ! S ! (Bool, Res, S')
61. Resource exists? FETCH THE INTERNAL REPRESENTATION OF THE RESOURCE 404 NOT FOUND REDIRECTION CREATION { 200 OK CONDITION VALIDATION DELETION UPDATE / REPLACE { Req ! Res ! S ! (Bool, Res, S')
63. c. 2007 by Sheehy, Latt, Gross et al Erlang, Ruby, Node.js, Go, Clojure, Perl, Scala, Haskell*
64. Restricted subset of HTTP/1.1 Declarative: derive facts about your resource Removes need to decide many things “Just leaky enough”
65. Full-stack web framework An “API tool” For processing arbitrary requests For Websockets “Easy” (but it is “correct”) Webmachine is NOT
66. Semantics
67. Semantics Req ! Res ! S ! (V, Res', S')
68. Semantics Req ! Res ! S ! (V, Res', S') predicate(ReqData, State) -> %% True referential transparency, %% through immutability {SomeValue, ReqData, State}. def predicate # @request, @response are bound # State is instance variables some_value end
69. Minimal Resource -module(sample_resource). -export([init/1, to_html/2]). -include_lib("webmachine/include/webmachine.hrl"). init(_) -> {ok, undefined}. to_html(RD, State) -> {"<html><body>Hello, world</body></html>", RD, State}.
70. Minimal Resource require 'webmachine' class SampleResource < Webmachine::Resource def to_html "<html><body>Hello, world</body></html>" end end
71. Debugging It’s nice to know where your errors are.
72. Implement The Good Parts
73. Safeguards allowed_methods(ReqData, State) -> {[‘GET’, ‘HEAD’], ReqData, State}. def malformed_request? request.query[‘q’] =~ /^[0-9]+$/ end
74. Authn/Authz is_authorized(ReqData, State) -> {check_token(ReqData), ReqData, State}. def forbidden? not @user.can_access?(request.uri) end
75. Content Negotiation content_types_provided(ReqData, State) -> {[{“text/html”, to_html}, {“application/hal+json”, to_hal}], ReqData, State}. def encodings_provided {‘gzip’ => :encode_gzip} end
76. Content Negotiation content_types_provided(ReqData, State) -> {[{“text/html”, to_html}, {“application/hal+json”, to_hal}], ReqData, State}. def encodings_provided {‘gzip’ => :encode_gzip} end
77. Conditional Requests last_modified(ReqData, State=#state{fi=F}) -> {F#file_info.mtime, ReqData, State}. def generate_etag @etag ||= Digest.md5(@content) end
78. Caching expires(ReqData, State) -> {qdate:add_months(2, now()), ReqData, State}.
79. Redirection/Obsoletion resource_exists(ReqData, State) -> {false, ReqData, State}. previously_existed(ReqData, State) -> {true, ReqData, State}. moved_permanently(ReqData, State) -> {{true, “http://google.com”}, ReqData, State}.
80. Future of Webmachine
85. More Languages!
86. Thank You! @SEANCRIBBS GITHUB.COM/SEANCRIBBS SEANCRIBBS.COM