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.

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

3. Richardson Maturity Model

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)

8. Let’s get started

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)

12. Resources == Nouns

13. Identification of Resources
Generally:
•/noun/id
•/noun/action/id

14. Collections too …
Generally
•/nouns
(notice the above is plural now)

15. Level 1: Resources

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?

31. Joël Franusic
Developer Evangelist
@jf

33. 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