On the Edge of Hypermeda

Stateless.. Nouns & Verbs.. Idempotent.. HTTP Auth.. Tokens.. We’ve all heard those phrases thrown around when we talk about REST. We’ve been told our systems have to include these characteristics or they’re not RESTful. We’ve talked over and over again on how to implement them. Unfortunately, somewhere along the way, we lost the answer to “why?” What’s the point? What value do we gain by doing things the “right” way?

Transcript

1. D. Keith Casey, Jr keith@caseysoftware.com / @CaseySoftware Austin, TX On the Edge of Hypermedia
2. D. Keith Casey, Jr - REST Summit 2012 So who are you? •D. Keith Casey, Jr •Developer Evangelist, Twilio •Project Lead, Web2Project •Community: Helped organize php|tek*3, antagonized DCPHP, agitating in Austin PHP
3. D. Keith Casey, Jr - REST Best Practices Stuff I do.. • https://github.com/web2project/web2project • https://github.com/twilio/twilio-php • https://github.com/twilio/OpenVBX • https://github.com/caseysoftware/contactually-php • https://github.com/caseysoftware/fullcontact-api-php • https://github.com/fullcontact/fullcontact-api-php • https://github.com/caseysoftware/getsatisfaction-php • https://github.com/caseysoftware/web2project-slim OPTIONS.. oh yeah.
4. D. Keith Casey, Jr - REST Best Practices Richardson Maturity Model
5. D. Keith Casey, Jr - REST Best Practices Speaking the same language..
6. D. Keith Casey, Jr - REST Best Practices The Constraints • Client-Server • Stateless • Cacheable • Layered System • Uniform Interfaces • Code on Demand (optional)
7. D. Keith Casey, Jr - REST Best Practices “Strictly RESTful” REST is not a standard
8. D. Keith Casey, Jr - REST Best Practices What REST is not.. •Pretty URLs •XML over HTTP •JSON over HTTP
9. D. Keith Casey, Jr - REST Best Practices Level 0: POX
   (on both your houses if you do this)
10. D. Keith Casey, Jr - REST Best Practices The Constraints • Client-Server • Stateless • Cacheable • Layered System • Uniform Interfaces • Code on Demand (optional)
11. D. Keith Casey, Jr - REST Best Practices Uniform Interfaces • Four Principles •Identification of Resources • Manipulation of Resources through these Representations • Self-descriptive Messages • Hypermedia as the engine of application state (HATEOAS)
12. D. Keith Casey, Jr - REST Best Practices Resources == Nouns
13. D. Keith Casey, Jr - REST Best Practices Identification of Resources •Generally •/noun/id •/noun/action/id •But not required •/?n=noun&id=id •/?n=noun&a=action&id=id
14. D. Keith Casey, Jr - REST Best Practices Collections too.. •Generally •/nouns •/nouns?page=n&limit=100 (notice the above are plural now)
15. D. Keith Casey, Jr - REST Best Practices Level 1: Resources
16. D. Keith Casey, Jr - REST Best Practices Uniform Interfaces • Four Principles •Identification of Resources • Manipulation of Resources through these Representations • Self-descriptive Messages • Hypermedia as the engine of application state (HATEOAS)
17. D. Keith Casey, Jr - REST Best Practices Manipulation through those Interfaces • Within Twilio: • /2010-04-01/Accounts/{AccountSid}/Calls/{CAxxx} • /2010-04-01/Accounts/{AccountSid}/Conferences/ {CFxxx} • /2010-04-01/Accounts/{AccountSid}/Notifications/ {NOxxx} • /2010-04-01/Accounts/{AccountSid}/Recordings/ {RExxx} • /2010-04-01/Accounts/{AccountSid}/Queues/{QUxxx} • /2010-04-01/Accounts/{AccountSid}/SMS/{SMxxx} • /2010-04-01/Accounts/{AccountSid}/Transcripts/ {TRxxx} • GET {none} • POST {only for Calls & SMS}
18. D. Keith Casey, Jr - REST Best Practices Level 2: HTTP Verbs
19. D. Keith Casey, Jr - REST Best Practices Uniform Interfaces • Four Principles •Identification of Resources • Manipulation of Resources through these Representations • Self-descriptive Messages • Hypermedia as the engine of application state (HATEOAS)
20. D. Keith Casey, Jr - REST Best Practices Self Descriptive •Each message should tell you: •how to process itself; •if that resource is cachable; •how to request the next resource;
21. D. Keith Casey, Jr - REST Best Practices Code on Demand
    (optional) •A request doesn’t just retrieve a resource but also the code to act upon it •We don’t have to know or understand the code, just how to run it •Allows for flexibility, upgradability
22. D. Keith Casey, Jr - REST Best Practices Ummm... gmail?
23. D. Keith Casey, Jr - REST Best Practices Level 3: Hypermedia Controls
24. D. Keith Casey, Jr - REST Best Practices Uniform Interfaces • Four Principles •Identification of Resources • Manipulation of Resources through these Representations • Self-descriptive Messages • Hypermedia as the engine of application state (HATEOAS)
25. D. Keith Casey, Jr - REST Best Practices HATEOAS Clients make state transitions only through actions that are dynamically identified within hypermedia by the server (e.g. by hyperlinks within hypertext). Except for simple fixed entry points to the application, a client does not assume that any particular actions will be available for any particular resources beyond those described in representations previously received from the server. Source: http://en.wikipedia.org/wiki/
26. D. Keith Casey, Jr - REST Best Practices Choose your own Adventure
27. D. Keith Casey, Jr - REST Best Practices HATEOAS - not good curl -I https://api.github.com/ HTTP/1.1 200 OK Server: GitHub.com Date: Sat, 20 Apr 2013 13:52:22 GMT Content-Type: application/json; charset=utf-8 Connection: keep-alive Status: 200 OK X-RateLimit-Limit: 60 X-RateLimit-Remaining: 59 X-GitHub-Media-Type: github.beta X-Content-Type-Options: nosniff Content-Length: 1729 Access-Control-Allow-Credentials: true Access-Control-Expose-Headers: Link, X- RateLimit-Limit, X-RateLimit-Remaining, X- OAuth-Scopes, X-Accepted-OAuth-Scopes
28. D. Keith Casey, Jr - REST Best Practices HATEOAS - good curl https://api.twilio.com/2010-04-01 <?xml version="1.0"?> <TwilioResponse> <Version> <Name>2010-04-01</Name> <Uri>/2010-04-01</Uri> <SubresourceUris> <Accounts>/2010-04-01/Accounts</Accounts> </SubresourceUris> </Version> </TwilioResponse>
29. D. Keith Casey, Jr - REST Best Practices HATEOAS - better <TwilioResponse> <Account> <Sid>ACxxxx</Sid> <FriendlyName>Do you like my friendly name?</FriendlyName> <Type>Full</Type> <Status>active</Status> <DateCreated>Wed, 02 Jan 2013 21:37:41 +0000</DateCreated> <DateUpdated>Fri, 04 Jan 2013 01:15:02 +0000</DateUpdated> <AuthToken>redacted</AuthToken> <Uri>/2010-04-01/Accounts/ACxxxx</Uri> <SubresourceUris> <AvailablePhoneNumbers>/2010-04-01/Accounts/ACxxxx/AvailablePhoneNumbers</AvailablePhoneNumbers> <Calls>/2010-04-01/Accounts/ACxxxx/Calls</Calls> <Conferences>/2010-04-01/Accounts/ACxxxx/Conferences</Conferences> <IncomingPhoneNumbers>/2010-04-01/Accounts/ACxxxx/IncomingPhoneNumbers</IncomingPhoneNumbers> <Notifications>/2010-04-01/Accounts/ACxxxx/Notifications</Notifications> <OutgoingCallerIds>/2010-04-01/Accounts/ACxxxx/OutgoingCallerIds</OutgoingCallerIds> <Queues>/2010-04-01/Accounts/ACxxxx/Queues</Queues> <Recordings>/2010-04-01/Accounts/ACxxxx/Recordings</Recordings> <Sandbox>/2010-04-01/Accounts/ACxxxx/Sandbox</Sandbox> <SMSMessages>/2010-04-01/Accounts/ACxxxx/SMS/Messages</SMSMessages> <Transcriptions>/2010-04-01/Accounts/ACxxxx/Transcriptions</Transcriptions> </SubresourceUris> </Account> </TwilioResponse>
30. D. Keith Casey, Jr - REST Best Practices HATEOAS - better <TwilioResponse> <Account> <Sid>ACxxxx</Sid> <FriendlyName>Do you like my friendly name?</FriendlyName> <Type>Full</Type> <Status>active</Status> <DateCreated>Wed, 02 Jan 2013 21:37:41 +0000</DateCreated> <DateUpdated>Fri, 04 Jan 2013 01:15:02 +0000</DateUpdated> <AuthToken>redacted</AuthToken> <Uri>/2010-04-01/Accounts/ACxxxx</Uri> <SubresourceUris> <AvailablePhoneNumbers>/2010-04-01/Accounts/ACxxxx/AvailablePhoneNumbers</AvailablePhoneNumbers> <Calls>/2010-04-01/Accounts/ACxxxx/Calls</Calls> <Conferences>/2010-04-01/Accounts/ACxxxx/Conferences</Conferences> <IncomingPhoneNumbers>/2010-04-01/Accounts/ACxxxx/IncomingPhoneNumbers</IncomingPhoneNumbers> <Notifications>/2010-04-01/Accounts/ACxxxx/Notifications</Notifications> <OutgoingCallerIds>/2010-04-01/Accounts/ACxxxx/OutgoingCallerIds</OutgoingCallerIds> <Queues>/2010-04-01/Accounts/ACxxxx/Queues</Queues> <Recordings>/2010-04-01/Accounts/ACxxxx/Recordings</Recordings> <Sandbox>/2010-04-01/Accounts/ACxxxx/Sandbox</Sandbox> <SMSMessages>/2010-04-01/Accounts/ACxxxx/SMS/Messages</SMSMessages> <Transcriptions>/2010-04-01/Accounts/ACxxxx/Transcriptions</Transcriptions> </SubresourceUris> </Account> </TwilioResponse>
31. D. Keith Casey, Jr - REST Best Practices HATEOAS - still just better <TwilioResponse> <Account> <Sid>ACxxxx</Sid> <FriendlyName>Do you like my friendly name?</FriendlyName> <Type>Full</Type> <Status>active</Status> <DateCreated>Wed, 02 Jan 2013 21:37:41 +0000</DateCreated> <DateUpdated>Fri, 04 Jan 2013 01:15:02 +0000</DateUpdated> <AuthToken>redacted</AuthToken> <Uri>/2010-04-01/Accounts/ACxxxx</Uri> <SubresourceUris> <AvailablePhoneNumbers>/2010-04-01/Accounts/ACxxxx/AvailablePhoneNumbers</AvailablePhoneNumbers> <Calls>/2010-04-01/Accounts/ACxxxx/Calls</Calls> <Conferences>/2010-04-01/Accounts/ACxxxx/Conferences</Conferences> <IncomingPhoneNumbers>/2010-04-01/Accounts/ACxxxx/IncomingPhoneNumbers</IncomingPhoneNumbers> <Notifications>/2010-04-01/Accounts/ACxxxx/Notifications</Notifications> <OutgoingCallerIds>/2010-04-01/Accounts/ACxxxx/OutgoingCallerIds</OutgoingCallerIds> <Queues>/2010-04-01/Accounts/ACxxxx/Queues</Queues> <Recordings>/2010-04-01/Accounts/ACxxxx/Recordings</Recordings> <Sandbox>/2010-04-01/Accounts/ACxxxx/Sandbox</Sandbox> <SMSMessages>/2010-04-01/Accounts/ACxxxx/SMS/Messages</SMSMessages> <Transcriptions>/2010-04-01/Accounts/ACxxxx/Transcriptions</Transcriptions> </SubresourceUris> </Account> </TwilioResponse>
32. D. Keith Casey, Jr - REST Best Practices Glory of REST.. eh?
34. D. Keith Casey, Jr - REST Best Practices Additional Resources
    (no pun intended) •http://en.wikipedia.org/wiki/HATEOAS •http://blog.steveklabnik.com/2011/07/03/ nobody-understands-rest-or-http.html - Steve Klabnik •http://shop.oreilly.com/product/ 9780596529260.do •http://videos.restfest.org
35. D. Keith Casey, Jr keith@caseysoftware.com / @CaseySoftware Austin, TX On the Edge of Hypermedia