The rise of Mobile and the diversity its technologies make exposing a RESTfull API the most crucial capability of any application and the key to its success. In the absence of widely adopted best practices and well-defined conventions, designing such an API is nothing but trivial. This presentation introduces the fundamentals of REST architecture, and discusses the principles of RESTfull design. Among the topics covered: resource modeling (URI design, and HTTP verbs/status code canonical usage), multiple representation support, testing, cache control, security (Http and OAuth), and API versioning. HATEOAS and REST maturity model are also discussed. No prior knowledge REST is required.

1. How Restful is Your Rest?
Abdelmonaim Remani
@PolymathicCoder
Øredev 2012
Malmö, Sweden

2. License
Creative Commons Attribution Non-Commercial 3.0 Unported
http://creativecommons.org/licenses/by-nc/3.0
Disclaimer: The graphics, logos, and trademarks used this presentation
belong to their rightful owners.

3. Trevligt att träffa dig nordisk
hackare!

4. About Me
Software Architect at Just.me Inc.
Interested in technology evangelism and enterprise software
development and architecture
Frequent speaker (JavaOne, JAX, OSCON, OREDEV, etc…)
Open-source advocate
President and founder of a number of user groups
NorCal Java User Group
The Silicon Valley Spring User Group
The Silicon Valley Dart Meetup
Bio: http://about.me/PolymathicCoder
Twitter: @PolymathicCoder
Email: abdelmonaim.remani@gmail.com

5. Let’s Get Started!

6. What is an API?
Application Programming Interface
You have an API when
(All or a part of) the functionality of your system is exposed
In the form a well-defined interface (or a collection of interfaces)
of services
That are externally accessible
And programmatically consumable through to a well-defined protocol
You have a Web API when
The functionality of your system is exposed
In the form of a collection of Web Services
That are publicly addressable through a set of Web endpoints (URLs)
And programmatically consumable though HTTP protocol

7. Why Bother?
Web 2.0
Convenience and standardization around accessing data and
services
Explosion of Open APIs
Location-Based (Maps, Geo-coding, Weather, Traffic, Etc…)
Financial Data
Social Data
Government Data, NGOs, etc…
Etc…

8. Why Bother?
The birth of Mashups (Hybrid Web Applications)
Combines services to create a value-added
Aggregate and visualize data in interesting ways
Spoiled user-base that demands a lot more than what
a single service can offer
I want to see the closest Moroccan restaurants to my
current location on a map along with consumer ratings
and whether any of my friends has recently checked-in
in the last 30 days

9. Why Bother?
Mobile
A lot more apps than browsers
Mobile traffic is diminishing web traffic exponentially
Mashups 2.0 is Mobile

10. Why Bother?
You goal behind exposing a Web API should be for your
services to be mashed up with others
Beneficial
Will drive traffic in your direction
Will allow you to learn about your own services and how they
are being used
Will create goodwill with new potential users
Implies
The majority of the traffic is NOT going to be through your
own app or website
Your App is the API it exposes

11. Challenges
You have very little control on how your API will be
used
You do not control how your services are orchestrated
(Used in combination)
Public APIs are forever
Better get it right the first time!

12. What’s Right?
How does a good API feel like?
Easy to learn and use
Intuitive
POLA (Principle of Least Astonishment)
Consistent
Based on standards
Adheres to a convention
Hard to misuse
Well-Documented

13. What is REST?

14. What is REST?
REpresentational State Transfer
Roy Fielding Dissertation (Chapter 5-6)
Architectural Styles and the Design of Network-based
Software Architectures
http://www.ics.uci.edu/~fielding/pubs/dissertation/top.h
tm

15. What is REST about?
Goals
Scalability
Generality of Interface
Independent Deployment of Component
Intermediary Components
Rest Constraints
Client-Server
Stateless Conversion
Cacheable
Uniform Interface
Layered System
Code on-demand (Optional)

16. What is REST about?
Leveraging the web as a platform
Resource-Oriented
Anything exposed on the web is a resource
(Documents, video, device, etc…)
Resources are identifiable and addressable by URIs
An architecture based on the HTTP protocol

17. API Design

18. Richardson Maturity Model
Leonard Richardson
http://www.crummy.com/writing/speaking/2008-Qcon/

19. The Address Book

20. The Address Book
A Simple address book that allows users to manage their contact data
A user has a username and is associated with a set of contacts
A contact is constitute of: a unique ID, a name, and a phone number
User Stories:
As a user, I want to add a contact to my address book
As a user, I want to list all contacts in my address book
As a user, I want to view a specific contact in my address book
As a user, I want to modify a specific contact in my address book
As a user, I want to delete a specific contact from my address book
As a user, I want to email a specific contact in my address book to a friend

21. Richardson Maturity Model
Level 0
Single URI
Identify all possible operations/functionality
indicate the desired operation in the payload
Single HTTP Verb

22. The Address Book at Level 0
SOAP-Based RPC Web Service
Endpoint
http://www.polymathiccoder.com:9999/ws/addressbook
WSDL
http://www. polymathiccoder.com:9999/ws/addressbook?wsdl
addContact(“bob”, “Abdel Remani”, “(123) 123-1234”)
lookupAllContacts(“bob”)
lookupContactById(“bob”, 123)
editContact(“bob”, 123, “Abdelmonaim Remani”, “(123) 123-
1234”)
deleteContact(“bob”, 123)
emailContact(“bob”, 123, “sandy@polymathiccoder.com”)
markAsFavorite(“bob”, 123)

23. Richardson Maturity Model
Level 1
Multiple URLs
One URL per method
URI encoded operations
Single Verb
GET is used to change stage
GET should be safe or idempotent

24. The Address Book at Level 1
URL Tunneling
Endpoints
http://www. polymathiccoder.com/addressbook/add-
contact?user=bob&name=Abdel%20Remani&phone-
number=(123)%20123-1234
http://www. polymathiccoder.com/addressbook/lookup-all-
contacts?user=bob
http://www. polymathiccoder.com/addressbook/lookup-
contact?user=bob&id=123
http://www. polymathiccoder.com/addressbook/edit-
contact?user=bob&id=123&name=Abdelmonaim%20Remani&phone-
number=(123)%20123-1234
http://www. polymathiccoder.com/addressbook/delete-
contact?user=bob&id=123
http://www.
polymathiccoder.com/addressbook/email?user=bob&id=123&to=sand
y@polymathiccoder.com
http://www. polymathiccoder.com/addressbook/mark-as-

25. Richardson Maturity Model
Level 2
Level 2
Many URI
Leverage multiple HTTP Verbs
You might call yourself Restful at this point
Creating a uniform interface based on the HTTP protocol

26. The Address Book at Level 2
The Restful Address Book

27. Recourse Identification
Find all the nouns in users stories

28. Recourse Identification
Here are all the nouns we found:
User
Uniquely identifiable by a username
Contact
Uniquely identifiable by an id
Let’s start calling nouns resources

29. Recourse Identification
Resources are identifiable and addressable by URIs
The collection of resources the same kind
Users
/users
Contacts
/contacts
The individual resources within its collections
The User whose username is “abdel”
/users/abdel
The Contact whose ID is “123”
/contacts/123

30. Recourse Identification
Is there association between any of our resources?
User has many Contacts
A User can is the parent resource of a Contact
Chaining resources together
“/” in a URI implies hierarchy
Contact whose id is “123” and owner is the User whose
username is “abdel”
/users/abdel/contacts/123

31. Recourse Identification
We end with 2 URIs referring to the same Contact
resource whose ID is “123”
/contcats/123
/users/abdel/contacts/123
We ask the question: Can a “Contact” recourse exist
independently from “User” resource?
The Answer is NO in this case
/contcats/123
/users/abdel/contacts/123

32. Leveraging HTTP Verbs
User Stories:

34. Leveraging HTTP Verbs
CRUD Operations map to HTTP Verbs
GET for Read
POST for Create
PUT for Update
DELETE for Delete

35. Leveraging HTTP Verbs
To view all Abdel’s contacts
GET /users/abdel/contacts
To view Abdel’s contact whose ID is 123
GET /users/abdel/contacts/123
To add a new contact to Abdel’s address book
POST /users/abdel/contacts
To update Abdel’s contact whose is ID is 123
PUT /users/abdel/contacts/123
To delete Abdel’s contact whose is ID is 123
DELETE /users/abdel/contacts/123

37. Non-CRUD
Non-CRUD operations do not map to HTTP verbs
Use descriptive verbs in URLs as Controller calls
To email Abdel’s contact whose ID is 123 to
sandy@polymathiccoder.com
GET
/users/abdel/contacts/123/email?to=sandy@polymathicc
oder.com
To mark Abdel’s contact whose ID is 123 to
sandy@polymathiccoder.com
PUT /users/abdel/contacts/123/mark-as-favorite

39. The Opinion Shop: URLs
Convention for your URLs
RFC 3986: URLs are case sensitive
No CAPS to avoid confusion
No camel-case
Links are usually underlined
Use Hyphens instead of Underscores for readability

40. Resource Representation
For a resource identified by the same URI
Representation in the form of MIME/Media Types
Multiple data representation is supported
Use “Accept” HTTP Header
Avoid file extensions
Manipulation is supported through multiple data
representation
Use “Content-Type” HTTP Header

41. The Opinion Shop: URLs
Convention object names in payload
No JavaScript Convention
http://javascript.crockford.com/code.html
No camel-case
I prefer using using Hyphens to be consistent with URLs

42. Leveraging HTTP Status Codes
1xx: Informational
2xx: Success
3xx: Redirection
4xx: Client Error
5xx: Server Error

43. Leveraging HTTP Status Codes
200 – OK
Success
Error with details in the body
201 – Created
202 – Accepted
400 – Bad Request
401 – Unauthorized
403 – Forbidden
404 – Not Found
405 – Method Not Allowed
406 – Not Acceptable
409 – Conflict
412 – Precondition Failed
415 – Unsupported Media Type
500 – Server Problems

44. Richardson Maturity Model
Level 4
HATEOAS
Hypermedia As The Engine Of Application Sate
Business Workflow
Capturing the different states of a resource
Transitions Endpoint
Returning all possible links given the current state of
the resource

45. Partials and Variations

46. Pagination
Use Query Parameters
Pagination
Don’t do this
/page/1
Inspired by SQL
?limit=20&offset=20
Inspired by RFC 5005: Feed Paging and Archiving
http://tools.ietf.org/html/rfc5005
?next=20&to-item=6783&inclusive=true
?prev=23&to-item=6783&inclusive=false

47. Ordering, Sorting and Fitering
Use Query Parameters
Ordering and Sorting
?order-by=populatrity&sorted-as=desc
?order-by=first-name&sorted-as=asc
Filtering
?filter-by=
Etc…

48. Views
Support custom views of the data at the schema level
Use an easy expression language
?fields=(first-name,phone-number)
?fields=!(last-name)
Google, LinkedIn, and others use a variations
Support different predefined views of the data
Use
?view=brief
?view=full

49. Legacy Clients

50. Legacy Clients
Older Clients
Only support GET and POST HTTP Methods
Use
?method=put

51. Security

52. Security
Remember that your Web Services must be stateless
Do not use cookies or HTTP session under any circumstances
The client must send credentials to autenticate with very call
Options
HTTP Security
Preemptively Setting “Authorization” HTTP Header
Basic or Digest
OAuth

53. Testing You API

54. Testing
Spring RestTemplate
http://static.springsource.org/spring/docs/3.1.x/spring-
framework-reference/html/remoting.html#rest-
resttemplate
Jayway’s Rest-Assured
http://code.google.com/p/rest-assured/

55. Versioning

56. Versioning
Don’t do this
/api/v1/…
?v=1
/api/v1.1/…
/api/07-19-2012/…
Use HTTP Headers
Use Vendor-Specific MIME/Media Types
Accept
application/vnd.polymathiccoder.addressbook+json

57. Documentation

58. Documentation
What to document
Endpoint
Description
Prerequisites
Request
Response

59. Documentation
What to document
Use a mind map

60. Documentation
Refer to other’s documentations
Twitter, Facebook, Google, etc…
ioDocs from Mashery
http://www.mashery.com/product/io-docs
Live Example:
http://developer.rottentomatoes.com/iodocs

61. How Restful Is REST?

62. How Restful Is Your REST?
Richardson Maturity Model as a reference
It’ll tell where you stand
How Restful do you want to be?
Dogmatic vs. Pragmatic
In Common Law, there is this concept of “The Reasonable
Man”
Being reasonable is relative
Look in similar situation
Similar expertise
Custom and usage

63. Question?

64. Recommended Reading

65. Tack själv!
PolymathicCoder