A brief tutorial on RESTful APIs

1. Coming to REST: Basic Stuff
@maxgoff
BIG SMART DATA

2. Coming to REST:
BIG SMART DATA
⁻ What is REST
⁻ REST Design Principles
⁻ REST Architecture Components
⁻ REST Design Guidelines

3. What is REST?
̵ Representational State Transfer
̵ Web Services Design Principles
̵ Focus: System’s Resources
̵ Simple HTTP transfer
̵ Lightweight alternative to RPC and
Web Services (SOAP, WSDL)
̵ Effectively replaced SOAP and WSDL
BIG SMART DATA
REST Origin: Doctoral Dissertation of Roy Thomas Fielding, PhD

4. What is REST?
̵ Platform Independent
̵ Language Independent
̵ Standards Based (HTTP)
̵ Can be used in the presence of firewalls
̵ REST is NOT a “standard”
BIG SMART DATA

5. Someone Special
345 Some Address
Some URL, WWW
127.0.0.1
Some Sender
012 Traceback Street
Some URL, WWW
198.168.1.1
Someone Special
345 Some Address
Some URL, WWW
127.0.0.1
REST vs SOAP
⁻ No envelope
⁻ Easier to handle
⁻ Waste less resources
BUT as secure(able) as SOAP
What is REST?

6. Four Basic Design Principles:
1) Use HTTP methods explicitly
2) Be stateless
3) Expose directory structure-like URLs
4) Transfer: XML, JSON, or both
BIG SMART DATA
REST Design Principles

7. Explicit HTTP methods:
BIG SMART DATA
CRUD Operation ≈ HTTP method ≈ SQL Equivalent
CREATE (resource on server) POST INSERT
READ (retrieve resource) GET SELECT
UPDATE (change or modify) PUT UPDATE
DELETE (destroy resource) DELETE DELETE
REST Design Principles
NOT a standard but a good idea

8. Be stateless:
BIG SMART DATA
Fig 1. Stateful design = bad
Source: http://www.ibm.com/developerworks/webservices/library/ws-restful
REST Design Principles

9. Be stateless:
BIG SMART DATA
Fig 2. Stateless design = good
Source: http://www.ibm.com/developerworks/webservices/library/ws-restful
Stateless design shifts the responsibility of maintaining
application state to the client
REST Design Principles

10. Expose directory structure-like URIs:
BIG SMART DATA
⁻ URI should be intuitive
⁻ Ideally, a self-documenting interface
⁻ Hierarchical, rooted at a single path
⁻ Design Affordance
REST Design Principles

11. Key components of REST architecture:
BIG SMART DATA
⁻ Resources
⁻ A web of resources
⁻ Client-server
⁻ No connection state
⁻ Resources should be cacheable
⁻ Proxy server friendly
REST Architecture Components

12. Resources:
BIG SMART DATA
⁻ Logical URLs: universally addressable
⁻ Key element of a true RESTful design
as opposed to “methods” or “services”
⁻ View object data as a resource
⁻ Resource contains all required information
or links to it
REST Architecture Components

13. A Web of Resources:
BIG SMART DATA
⁻ An arbitrary resource ought not be excessively
large and contain too fine-grained details
⁻ A resource ought to contain links to
additional information, just like a web page
REST Architecture Components

14. Client-Server:
BIG SMART DATA
⁻ Simple client-server assumption
⁻ One component’s server can be another
component’s client
REST Architecture Components

15. No Connection State:
BIG SMART DATA
⁻ Interaction is stateless
⁻ Servers and resources can be stateful
⁻ Each request carries all required information
⁻ No reliance on previous interactions
REST Architecture Components

16. Cacheable:
BIG SMART DATA
⁻ Resources should be cacheable
(when possible)
⁻ Protocols must allow server to specify
⁻ HTTP/HTTPS universally used
REST Architecture Components
Proxy servers:
⁻ Any standard HTTP proxy can be used

17. BIG SMART DATA
⁻ URLs
⁻ Queries
⁻ Documentation
⁻ GET v POST
⁻ Best Practices
REST Design Guidelines

18. BIG SMART DATA
⁻ Do not use “physical” URLs
⁻ Use logical URLs
REST Design Guidelines
URLs:
http://www.bigsmartdata.com/inventory/product123.xml
http://www.bigsmartdata.com/inventory/product/123

19. BIG SMART DATA
⁻ Should not return an overload of data
⁻ If needed, provide a paging mechanism:
eg: a “product list” GET request
returns the first N products
with next/prev links
REST Design Guidelines
Queries:

20. BIG SMART DATA
⁻ REST response can be anything, but …
⁻ APIs should be well documented
⁻ Do not change output format lightly
⁻ REMEMBER: Non-human clients
⁻ If output is XML, document with
schema or DTD
REST Design Guidelines
Documentation:

21. BIG SMART DATA
⁻ GET requests should never cause
a state change
⁻ Anything causing server state change
should be POST or other HTTP verbs
REST Design Guidelines
GET v POST:

22. BIG SMART DATA
⁻ Returns Include Actual URLs
⁻ instead of:
http://bigsmartdata.com/product/PRODUCT_ID
⁻ return:
http://bigsmartdata.com/product/012345 ...
REST Design Guidelines
Best Practices:
Output is larger but clients are more
easily directed to new URLs as needed

23. BIG SMART DATA
⁻ Keep Things Simple
⁻ Use 2 Base URLs per resource
⁻ Two fundamental abstractions:
⁻ Collections (Collection Resource)
⁻ Elements within Collections
(Instance Resource)
⁻ Use Ordinal Numbers for Versions
REST Design Guidelines
Best Practices:

24. BIG SMART DATA
⁻ Nouns are the new verbs
⁻ Use a noun to describe the action
⁻ The noun is the resource:
REST Design Guidelines
Best Practices:
Verb based Noun based
The project is validated by owner A project validation is created
The user deactivates the account A user account activation is deleted
A user subscribes to a group A subscription is created

25. RESTful Resources
Tutorials:
Pearson College “Learn REST”:
http://www.restapitutorial.com
Apigee YouTube Channel:
http://www.youtube.com/user/apigee
Learn REST:
http://rest.elkstein.org/
Resources:
IBM Developer Works:
http://www.ibm.com/developerworks/webservices/library/ws-restful/
HTTP Status Codes:
http://httpstatus.es/
Original Dissertation:
http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm
BIG SMART DATA

26. http://about.me/maxgoff
http://linkedin.com/in/maxgoff
http://bigsmartdata.com
@maxgoff
BIG SMART DATA