Best Practices for RESTful Web
Services
Joël Franusic, Developer Evangelist, Twilio
Joël Franusic
Developer Evangelist, Twilio
@jf
https://github.com/jpf
Richardson Maturity Model
Speaking the same language …
“Strictly RESTful”
REST is not a standard
What REST is not …
• Pretty URLs
• XML over HTTP
• JSON over HTTP
The Constraints
• Client-Server
• Stateless
• Cacheable
• Uniform Interfaces
• Layered System
• Code on Demand (optional)
Let’s get started
Level 0: POX
The Constraints
• Client-Server
• Stateless
• Cacheable
• Layered System
• Uniform Interfaces
• Code on Demand (optional)
Uniform Interfaces
Four principles:
1.Identification of Resources
2.Manipulation of Resources through these Representation...
Resources == Nouns
Identification of Resources
Generally:
•/noun/id
•/noun/action/id
Collections too …
Generally
•/nouns
(notice the above is plural now)
Level 1: Resources
Uniform Interfaces
Four principles:
1.Identification of Resources
2.Manipulation of Resources through these Representation...
Manipulation through those
Interfaces
Within Twilio:
/2010-04-01/Accounts/{AccountSid}/Calls/{CAxxx}
/2010-04-01/Accounts/...
Level 2: HTTP Verbs
Uniform Interfaces
Four principles:
1.Identification of Resources
2.Manipulation of Resources through these Representation...
Self Descriptive
Each message should tell you:
•How to process itself
•If that resource is cacheable
•How to request the n...
Level 3: Hypermedia Controls
Uniform Interfaces
Four principles:
1.Identification of Resources
2.Manipulation of Resources through these Representation...
HATEOAS
“Clients make state transitions only through actions that are
dynamically identified within hypermedia by the serv...
Choose Your Own Adventure
For example:
$ curl https://api.twilio.com/2010-04-01
<?xml version="1.0"?>
<TwilioResponse>
<Version>
<Name>2010-04-01</N...
Another example:
<TwilioResponse>
<Account>
<Sid>ACxxxx</Sid>
<FriendlyName>Do you like my friendly name?</FriendlyName>
<...
Another example:
<TwilioResponse>
<Account>
<Sid>ACxxxx</Sid>
<FriendlyName>Do you like my friendly name?</FriendlyName>
<...
Another example:
<TwilioResponse>
<Account>
<Sid>ACxxxx</Sid>
<FriendlyName>Do you like my friendly name?</FriendlyName>
<...
Glory of REST.. eh?
Joël Franusic
Developer Evangelist
@jf
Additional Resources
•

http://en.wikipedia.org/wiki/http://en.wikipedia.org/wiki/HATEOAS

•

http://blog.steveklabnik.com...
Best Practices for RESTful Web Services
Best Practices for RESTful Web Services
Upcoming SlideShare
Loading in …5
×

Best Practices for RESTful Web Services

1,341 views

Published on

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.

Published in: Technology
0 Comments
1 Like
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total views
1,341
On SlideShare
0
From Embeds
0
Number of Embeds
2
Actions
Shares
0
Downloads
44
Comments
0
Likes
1
Embeds 0
No embeds

No notes for slide

Best Practices for RESTful Web Services

  1. 1. Best Practices for RESTful Web Services Joël Franusic, Developer Evangelist, Twilio
  2. 2. Joël Franusic Developer Evangelist, Twilio @jf https://github.com/jpf
  3. 3. Richardson Maturity Model
  4. 4. Speaking the same language …
  5. 5. “Strictly RESTful” REST is not a standard
  6. 6. What REST is not … • Pretty URLs • XML over HTTP • JSON over HTTP
  7. 7. The Constraints • Client-Server • Stateless • Cacheable • Uniform Interfaces • Layered System • Code on Demand (optional)
  8. 8. Let’s get started
  9. 9. Level 0: POX
  10. 10. The Constraints • Client-Server • Stateless • Cacheable • Layered System • Uniform Interfaces • Code on Demand (optional)
  11. 11. Uniform Interfaces Four principles: 1.Identification of Resources 2.Manipulation of Resources through these Representations 3.Self-descriptive Messages 4.Hypermedia as the engine of application state (HATEOAS)
  12. 12. Resources == Nouns
  13. 13. Identification of Resources Generally: •/noun/id •/noun/action/id
  14. 14. Collections too … Generally •/nouns (notice the above is plural now)
  15. 15. Level 1: Resources
  16. 16. Uniform Interfaces Four principles: 1.Identification of Resources 2.Manipulation of Resources through these Representations 3.Self-descriptive Messages 4.Hypermedia as the engine of application state (HATEOAS)
  17. 17. 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 POST PUT DELETE {none} {only for Calls & SMS} n/a {only for Recordings} OPTIONS, HEAD, PATCH, TRACE, CONNECT
  18. 18. Level 2: HTTP Verbs
  19. 19. Uniform Interfaces Four principles: 1.Identification of Resources 2.Manipulation of Resources through these Representations 3.Self-descriptive Messages 4.Hypermedia as the engine of application state (HATEOAS)
  20. 20. Self Descriptive Each message should tell you: •How to process itself •If that resource is cacheable •How to request the next resource
  21. 21. Level 3: Hypermedia Controls
  22. 22. Uniform Interfaces Four principles: 1.Identification of Resources 2.Manipulation of Resources through these Representations 3.Self-descriptive Messages 4.Hypermedia as the engine of application state (HATEOAS)
  23. 23. 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)
  24. 24. Choose Your Own Adventure
  25. 25. 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>
  26. 26. 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>
  27. 27. 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>
  28. 28. 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>
  29. 29. Glory of REST.. eh?
  30. 30. Joël Franusic Developer Evangelist @jf
  31. 31. Additional Resources • http://en.wikipedia.org/wiki/http://en.wikipedia.org/wiki/HATEOAS • http://blog.steveklabnik.com/2011/07/03/nobody-understandsrest-or-http://blog.steveklabnik.com/2011/07/03/nobodyunderstands-rest-or-http.html • http://shop.oreilly.com/product/9780596529260.http://shop. oreilly.com/product/9780596529260.do • http://http://videos.restfest.org

×