best practices for restful web services
DESCRIPTION
When we discuss APIs, most people immediately think of OAuth, GET and POST, and JSON. Few people think of the underlying concepts of nouns and verbs, idempotence, and uniform interfaces. Even less consider how we can combine these concepts into hypermedia to build APIs that are useful, logical, and future-friendly. Join us as we combine the basics, explore the larger concepts, and look at the standards that are leading the way.TRANSCRIPT
![Page 1: Best Practices for RESTful Web Services](https://reader034.vdocument.in/reader034/viewer/2022052618/554f6e20b4c905bb178b4fd7/html5/thumbnails/1.jpg)
Best Practices for RESTful Web Services
Joël Franusic, Developer Evangelist, Twilio
![Page 2: Best Practices for RESTful Web Services](https://reader034.vdocument.in/reader034/viewer/2022052618/554f6e20b4c905bb178b4fd7/html5/thumbnails/2.jpg)
Joël FranusicDeveloper Evangelist, Twilio@jfhttps://github.com/jpf
![Page 3: Best Practices for RESTful Web Services](https://reader034.vdocument.in/reader034/viewer/2022052618/554f6e20b4c905bb178b4fd7/html5/thumbnails/3.jpg)
Richardson Maturity Model
![Page 4: Best Practices for RESTful Web Services](https://reader034.vdocument.in/reader034/viewer/2022052618/554f6e20b4c905bb178b4fd7/html5/thumbnails/4.jpg)
Speaking the same language …
![Page 5: Best Practices for RESTful Web Services](https://reader034.vdocument.in/reader034/viewer/2022052618/554f6e20b4c905bb178b4fd7/html5/thumbnails/5.jpg)
“Strictly RESTful”
REST is not a standard
![Page 6: Best Practices for RESTful Web Services](https://reader034.vdocument.in/reader034/viewer/2022052618/554f6e20b4c905bb178b4fd7/html5/thumbnails/6.jpg)
What REST is not …
• Pretty URLs• XML over HTTP• JSON over HTTP
![Page 7: Best Practices for RESTful Web Services](https://reader034.vdocument.in/reader034/viewer/2022052618/554f6e20b4c905bb178b4fd7/html5/thumbnails/7.jpg)
The Constraints•Client-Server•Stateless•Cacheable•Uniform Interfaces•Layered System•Code on Demand (optional)
![Page 8: Best Practices for RESTful Web Services](https://reader034.vdocument.in/reader034/viewer/2022052618/554f6e20b4c905bb178b4fd7/html5/thumbnails/8.jpg)
Let’s get started
![Page 9: Best Practices for RESTful Web Services](https://reader034.vdocument.in/reader034/viewer/2022052618/554f6e20b4c905bb178b4fd7/html5/thumbnails/9.jpg)
Level 0: POX
![Page 10: Best Practices for RESTful Web Services](https://reader034.vdocument.in/reader034/viewer/2022052618/554f6e20b4c905bb178b4fd7/html5/thumbnails/10.jpg)
The Constraints•Client-Server•Stateless•Cacheable•Layered System•Uniform Interfaces•Code on Demand (optional)
![Page 11: Best Practices for RESTful Web Services](https://reader034.vdocument.in/reader034/viewer/2022052618/554f6e20b4c905bb178b4fd7/html5/thumbnails/11.jpg)
Uniform InterfacesFour principles:
1.Identification of Resources2.Manipulation of Resources through these Representations3.Self-descriptive Messages4.Hypermedia as the engine of application state (HATEOAS)
![Page 12: Best Practices for RESTful Web Services](https://reader034.vdocument.in/reader034/viewer/2022052618/554f6e20b4c905bb178b4fd7/html5/thumbnails/12.jpg)
Resources == Nouns
![Page 13: Best Practices for RESTful Web Services](https://reader034.vdocument.in/reader034/viewer/2022052618/554f6e20b4c905bb178b4fd7/html5/thumbnails/13.jpg)
Identification of ResourcesGenerally:•/noun/id•/noun/action/id
![Page 14: Best Practices for RESTful Web Services](https://reader034.vdocument.in/reader034/viewer/2022052618/554f6e20b4c905bb178b4fd7/html5/thumbnails/14.jpg)
Collections too …Generally•/nouns
(notice the above is plural now)
![Page 15: Best Practices for RESTful Web Services](https://reader034.vdocument.in/reader034/viewer/2022052618/554f6e20b4c905bb178b4fd7/html5/thumbnails/15.jpg)
Level 1: Resources
![Page 16: Best Practices for RESTful Web Services](https://reader034.vdocument.in/reader034/viewer/2022052618/554f6e20b4c905bb178b4fd7/html5/thumbnails/16.jpg)
Uniform InterfacesFour principles:
1.Identification of Resources2.Manipulation of Resources through these Representations3.Self-descriptive Messages4.Hypermedia as the engine of application state (HATEOAS)
![Page 17: Best Practices for RESTful Web Services](https://reader034.vdocument.in/reader034/viewer/2022052618/554f6e20b4c905bb178b4fd7/html5/thumbnails/17.jpg)
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}PUT n/aDELETE {only for Recordings}OPTIONS, HEAD, PATCH, TRACE, CONNECT
![Page 18: Best Practices for RESTful Web Services](https://reader034.vdocument.in/reader034/viewer/2022052618/554f6e20b4c905bb178b4fd7/html5/thumbnails/18.jpg)
Level 2: HTTP Verbs
![Page 19: Best Practices for RESTful Web Services](https://reader034.vdocument.in/reader034/viewer/2022052618/554f6e20b4c905bb178b4fd7/html5/thumbnails/19.jpg)
Uniform InterfacesFour principles:
1.Identification of Resources2.Manipulation of Resources through these Representations3.Self-descriptive Messages4.Hypermedia as the engine of application state (HATEOAS)
![Page 20: Best Practices for RESTful Web Services](https://reader034.vdocument.in/reader034/viewer/2022052618/554f6e20b4c905bb178b4fd7/html5/thumbnails/20.jpg)
Self DescriptiveEach message should tell you:•How to process itself•If that resource is cacheable•How to request the next resource
![Page 21: Best Practices for RESTful Web Services](https://reader034.vdocument.in/reader034/viewer/2022052618/554f6e20b4c905bb178b4fd7/html5/thumbnails/21.jpg)
Level 3: Hypermedia Controls
![Page 22: Best Practices for RESTful Web Services](https://reader034.vdocument.in/reader034/viewer/2022052618/554f6e20b4c905bb178b4fd7/html5/thumbnails/22.jpg)
Uniform InterfacesFour principles:
1.Identification of Resources2.Manipulation of Resources through these Representations3.Self-descriptive Messages4.Hypermedia as the engine of application state (HATEOAS)
![Page 23: Best Practices for RESTful Web Services](https://reader034.vdocument.in/reader034/viewer/2022052618/554f6e20b4c905bb178b4fd7/html5/thumbnails/23.jpg)
HATEOAS“Clients make state transitions only through actions that are dynamically identified within hypermedia by the server (e.g., by hyperlinks“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 action is available for any particular resources beyond those described in representations previously received from the server.”
Source: http://en.wikipedia.org/wiki/Representational_state_transfer#Guiding_principles_of_the_interface (Accessed 2013-11-01)
![Page 24: Best Practices for RESTful Web Services](https://reader034.vdocument.in/reader034/viewer/2022052618/554f6e20b4c905bb178b4fd7/html5/thumbnails/24.jpg)
Choose Your Own Adventure
![Page 25: Best Practices for RESTful Web Services](https://reader034.vdocument.in/reader034/viewer/2022052618/554f6e20b4c905bb178b4fd7/html5/thumbnails/25.jpg)
For example:$ 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>
![Page 26: Best Practices for RESTful Web Services](https://reader034.vdocument.in/reader034/viewer/2022052618/554f6e20b4c905bb178b4fd7/html5/thumbnails/26.jpg)
Another example:<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>
![Page 27: Best Practices for RESTful Web Services](https://reader034.vdocument.in/reader034/viewer/2022052618/554f6e20b4c905bb178b4fd7/html5/thumbnails/27.jpg)
Another example:<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>
![Page 28: Best Practices for RESTful Web Services](https://reader034.vdocument.in/reader034/viewer/2022052618/554f6e20b4c905bb178b4fd7/html5/thumbnails/28.jpg)
Another example:<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>
![Page 29: Best Practices for RESTful Web Services](https://reader034.vdocument.in/reader034/viewer/2022052618/554f6e20b4c905bb178b4fd7/html5/thumbnails/29.jpg)
Glory of REST.. eh?
![Page 30: Best Practices for RESTful Web Services](https://reader034.vdocument.in/reader034/viewer/2022052618/554f6e20b4c905bb178b4fd7/html5/thumbnails/30.jpg)
![Page 31: Best Practices for RESTful Web Services](https://reader034.vdocument.in/reader034/viewer/2022052618/554f6e20b4c905bb178b4fd7/html5/thumbnails/31.jpg)
Joël Franusic
Developer Evangelist@jf
![Page 32: Best Practices for RESTful Web Services](https://reader034.vdocument.in/reader034/viewer/2022052618/554f6e20b4c905bb178b4fd7/html5/thumbnails/32.jpg)
![Page 33: Best Practices for RESTful Web Services](https://reader034.vdocument.in/reader034/viewer/2022052618/554f6e20b4c905bb178b4fd7/html5/thumbnails/33.jpg)
Additional Resources• http://en.wikipedia.org/wiki/http://en.wikipedia.org/wiki/HATEOAS• http://blog.steveklabnik.com/2011/07/03/nobody-understands-
rest-or-http://blog.steveklabnik.com/2011/07/03/nobody-understands-rest-or-http.html
• http://shop.oreilly.com/product/9780596529260.http://shop.oreilly.com/product/9780596529260.do
• http://http://videos.restfest.org