Best Practices for RESTful Web Services
2 likes3,740 views
The document outlines best practices for creating RESTful web services, emphasizing essential REST principles such as client-server architecture, statelessness, cacheability, and uniform interfaces. It discusses the importance of resource identification and manipulation, self-descriptive messages, and hypermedia controls through HATEOAS. Examples from Twilio's API illustrate how to implement these principles with specific endpoint structures and HTTP methods.
Best Practices for RESTful Web Services
- 1. Best Practices for RESTful Web Services Joël Franusic, Developer Evangelist, Twilio
- 2. Joël Franusic Developer Evangelist, Twilio @jf https://github.com/jpf
- 4. Speaking the same language …
- 5. “Strictly RESTful” REST is not a standard
- 6. What REST is not … • Pretty URLs • XML over HTTP • JSON over HTTP
- 7. The Constraints • Client-Server • Stateless • Cacheable • Uniform Interfaces • Layered System • Code on Demand (optional)
- 9. Level 0: POX
- 10. The Constraints • Client-Server • Stateless • Cacheable • Layered System • Uniform Interfaces • Code on Demand (optional)
- 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)
- 14. Collections too … Generally •/nouns (notice the above is plural now)
- 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. 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. Level 2: HTTP Verbs
- 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. Self Descriptive Each message should tell you: •How to process itself •If that resource is cacheable •How to request the next resource
- 21. Level 3: Hypermedia Controls
- 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. 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. Choose Your Own Adventure
- 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. 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. 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. 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. Glory of REST.. eh?