how restful is your rest?
DESCRIPTION
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.TRANSCRIPT
![Page 1: How RESTful Is Your REST?](https://reader031.vdocuments.us/reader031/viewer/2022012922/5563a3a9d8b42a2d538b541f/html5/thumbnails/1.jpg)
How Restful is Your Rest?Abdelmonaim Remani
@PolymathicCoder
Øredev 2012Malmö, Sweden
![Page 2: How RESTful Is Your REST?](https://reader031.vdocuments.us/reader031/viewer/2022012922/5563a3a9d8b42a2d538b541f/html5/thumbnails/2.jpg)
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.
License
![Page 3: How RESTful Is Your REST?](https://reader031.vdocuments.us/reader031/viewer/2022012922/5563a3a9d8b42a2d538b541f/html5/thumbnails/3.jpg)
Trevligt att träffa dig nordisk hackare!
![Page 4: How RESTful Is Your REST?](https://reader031.vdocuments.us/reader031/viewer/2022012922/5563a3a9d8b42a2d538b541f/html5/thumbnails/4.jpg)
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: [email protected]
About Me
![Page 5: How RESTful Is Your REST?](https://reader031.vdocuments.us/reader031/viewer/2022012922/5563a3a9d8b42a2d538b541f/html5/thumbnails/5.jpg)
Let’s Get Started!
![Page 6: How RESTful Is Your REST?](https://reader031.vdocuments.us/reader031/viewer/2022012922/5563a3a9d8b42a2d538b541f/html5/thumbnails/6.jpg)
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
What is an API?
![Page 7: How RESTful Is Your REST?](https://reader031.vdocuments.us/reader031/viewer/2022012922/5563a3a9d8b42a2d538b541f/html5/thumbnails/7.jpg)
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…
Why Bother?
![Page 8: How RESTful Is Your REST?](https://reader031.vdocuments.us/reader031/viewer/2022012922/5563a3a9d8b42a2d538b541f/html5/thumbnails/8.jpg)
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
Why Bother?
![Page 9: How RESTful Is Your REST?](https://reader031.vdocuments.us/reader031/viewer/2022012922/5563a3a9d8b42a2d538b541f/html5/thumbnails/9.jpg)
Mobile A lot more apps than browsers Mobile traffic is diminishing web traffic
exponentially Mashups 2.0 is Mobile
Why Bother?
![Page 10: How RESTful Is Your REST?](https://reader031.vdocuments.us/reader031/viewer/2022012922/5563a3a9d8b42a2d538b541f/html5/thumbnails/10.jpg)
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
Why Bother?
![Page 11: How RESTful Is Your REST?](https://reader031.vdocuments.us/reader031/viewer/2022012922/5563a3a9d8b42a2d538b541f/html5/thumbnails/11.jpg)
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!
Challenges
![Page 12: How RESTful Is Your REST?](https://reader031.vdocuments.us/reader031/viewer/2022012922/5563a3a9d8b42a2d538b541f/html5/thumbnails/12.jpg)
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
What’s Right?
![Page 13: How RESTful Is Your REST?](https://reader031.vdocuments.us/reader031/viewer/2022012922/5563a3a9d8b42a2d538b541f/html5/thumbnails/13.jpg)
What is REST?
![Page 14: How RESTful Is Your REST?](https://reader031.vdocuments.us/reader031/viewer/2022012922/5563a3a9d8b42a2d538b541f/html5/thumbnails/14.jpg)
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.htm
What is REST?
![Page 15: How RESTful Is Your REST?](https://reader031.vdocuments.us/reader031/viewer/2022012922/5563a3a9d8b42a2d538b541f/html5/thumbnails/15.jpg)
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)
What is REST about?
![Page 16: How RESTful Is Your REST?](https://reader031.vdocuments.us/reader031/viewer/2022012922/5563a3a9d8b42a2d538b541f/html5/thumbnails/16.jpg)
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
What is REST about?
![Page 17: How RESTful Is Your REST?](https://reader031.vdocuments.us/reader031/viewer/2022012922/5563a3a9d8b42a2d538b541f/html5/thumbnails/17.jpg)
API Design
![Page 18: How RESTful Is Your REST?](https://reader031.vdocuments.us/reader031/viewer/2022012922/5563a3a9d8b42a2d538b541f/html5/thumbnails/18.jpg)
Leonard Richardson http://www.crummy.com/writing/speaking/2008
-Qcon/
Richardson Maturity Model
![Page 19: How RESTful Is Your REST?](https://reader031.vdocuments.us/reader031/viewer/2022012922/5563a3a9d8b42a2d538b541f/html5/thumbnails/19.jpg)
The Address Book
![Page 20: How RESTful Is Your REST?](https://reader031.vdocuments.us/reader031/viewer/2022012922/5563a3a9d8b42a2d538b541f/html5/thumbnails/20.jpg)
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
The Address Book
![Page 21: How RESTful Is Your REST?](https://reader031.vdocuments.us/reader031/viewer/2022012922/5563a3a9d8b42a2d538b541f/html5/thumbnails/21.jpg)
Single URI Identify all possible operations/functionality indicate the desired operation in the payload
Single HTTP Verb
Richardson Maturity ModelLevel 0
![Page 22: How RESTful Is Your REST?](https://reader031.vdocuments.us/reader031/viewer/2022012922/5563a3a9d8b42a2d538b541f/html5/thumbnails/22.jpg)
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, “[email protected]”) markAsFavorite(“bob”, 123)
The Address Book at Level 0
![Page 23: How RESTful Is Your REST?](https://reader031.vdocuments.us/reader031/viewer/2022012922/5563a3a9d8b42a2d538b541f/html5/thumbnails/23.jpg)
Multiple URLs One URL per method URI encoded operations
Single Verb GET is used to change stage GET should be safe or idempotent
Richardson Maturity ModelLevel 1
![Page 24: How RESTful Is Your REST?](https://reader031.vdocuments.us/reader031/viewer/2022012922/5563a3a9d8b42a2d538b541f/html5/thumbnails/24.jpg)
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&[email protected]
http://www. polymathiccoder.com/addressbook/mark-as-favorite?user=bob&id=123
The Address Book at Level 1
![Page 25: How RESTful Is Your REST?](https://reader031.vdocuments.us/reader031/viewer/2022012922/5563a3a9d8b42a2d538b541f/html5/thumbnails/25.jpg)
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
Richardson Maturity ModelLevel 2
![Page 26: How RESTful Is Your REST?](https://reader031.vdocuments.us/reader031/viewer/2022012922/5563a3a9d8b42a2d538b541f/html5/thumbnails/26.jpg)
The Address Book at Level 2
The Restful Address Book
![Page 27: How RESTful Is Your REST?](https://reader031.vdocuments.us/reader031/viewer/2022012922/5563a3a9d8b42a2d538b541f/html5/thumbnails/27.jpg)
Find all the nouns in users stories
Recourse Identification
![Page 28: How RESTful Is Your REST?](https://reader031.vdocuments.us/reader031/viewer/2022012922/5563a3a9d8b42a2d538b541f/html5/thumbnails/28.jpg)
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
Recourse Identification
![Page 29: How RESTful Is Your REST?](https://reader031.vdocuments.us/reader031/viewer/2022012922/5563a3a9d8b42a2d538b541f/html5/thumbnails/29.jpg)
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
Recourse Identification
![Page 30: How RESTful Is Your REST?](https://reader031.vdocuments.us/reader031/viewer/2022012922/5563a3a9d8b42a2d538b541f/html5/thumbnails/30.jpg)
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
Recourse Identification
![Page 31: How RESTful Is Your REST?](https://reader031.vdocuments.us/reader031/viewer/2022012922/5563a3a9d8b42a2d538b541f/html5/thumbnails/31.jpg)
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
Recourse Identification
![Page 32: How RESTful Is Your REST?](https://reader031.vdocuments.us/reader031/viewer/2022012922/5563a3a9d8b42a2d538b541f/html5/thumbnails/32.jpg)
User Stories:
Leveraging HTTP Verbs
![Page 33: How RESTful Is Your REST?](https://reader031.vdocuments.us/reader031/viewer/2022012922/5563a3a9d8b42a2d538b541f/html5/thumbnails/33.jpg)
![Page 34: How RESTful Is Your REST?](https://reader031.vdocuments.us/reader031/viewer/2022012922/5563a3a9d8b42a2d538b541f/html5/thumbnails/34.jpg)
CRUD Operations map to HTTP Verbs GET for Read POST for Create PUT for Update DELETE for Delete
Leveraging HTTP Verbs
![Page 35: How RESTful Is Your REST?](https://reader031.vdocuments.us/reader031/viewer/2022012922/5563a3a9d8b42a2d538b541f/html5/thumbnails/35.jpg)
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
Leveraging HTTP Verbs
![Page 36: How RESTful Is Your REST?](https://reader031.vdocuments.us/reader031/viewer/2022012922/5563a3a9d8b42a2d538b541f/html5/thumbnails/36.jpg)
![Page 37: How RESTful Is Your REST?](https://reader031.vdocuments.us/reader031/viewer/2022012922/5563a3a9d8b42a2d538b541f/html5/thumbnails/37.jpg)
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 [email protected] GET /users/abdel/contacts/123/email?
[email protected] To mark Abdel’s contact whose ID is 123 to
[email protected] PUT /users/abdel/contacts/123/mark-as-favorite
Non-CRUD
![Page 38: How RESTful Is Your REST?](https://reader031.vdocuments.us/reader031/viewer/2022012922/5563a3a9d8b42a2d538b541f/html5/thumbnails/38.jpg)
![Page 39: How RESTful Is Your REST?](https://reader031.vdocuments.us/reader031/viewer/2022012922/5563a3a9d8b42a2d538b541f/html5/thumbnails/39.jpg)
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
The Opinion Shop: URLs
![Page 40: How RESTful Is Your REST?](https://reader031.vdocuments.us/reader031/viewer/2022012922/5563a3a9d8b42a2d538b541f/html5/thumbnails/40.jpg)
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
Resource Representation
![Page 41: How RESTful Is Your REST?](https://reader031.vdocuments.us/reader031/viewer/2022012922/5563a3a9d8b42a2d538b541f/html5/thumbnails/41.jpg)
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
The Opinion Shop: URLs
![Page 42: How RESTful Is Your REST?](https://reader031.vdocuments.us/reader031/viewer/2022012922/5563a3a9d8b42a2d538b541f/html5/thumbnails/42.jpg)
1xx: Informational 2xx: Success 3xx: Redirection 4xx: Client Error 5xx: Server Error
Leveraging HTTP Status Codes
![Page 43: How RESTful Is Your REST?](https://reader031.vdocuments.us/reader031/viewer/2022012922/5563a3a9d8b42a2d538b541f/html5/thumbnails/43.jpg)
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
Leveraging HTTP Status Codes
![Page 44: How RESTful Is Your REST?](https://reader031.vdocuments.us/reader031/viewer/2022012922/5563a3a9d8b42a2d538b541f/html5/thumbnails/44.jpg)
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
Richardson Maturity ModelLevel 4
![Page 45: How RESTful Is Your REST?](https://reader031.vdocuments.us/reader031/viewer/2022012922/5563a3a9d8b42a2d538b541f/html5/thumbnails/45.jpg)
Partials and Variations
![Page 46: How RESTful Is Your REST?](https://reader031.vdocuments.us/reader031/viewer/2022012922/5563a3a9d8b42a2d538b541f/html5/thumbnails/46.jpg)
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
Pagination
![Page 47: How RESTful Is Your REST?](https://reader031.vdocuments.us/reader031/viewer/2022012922/5563a3a9d8b42a2d538b541f/html5/thumbnails/47.jpg)
Use Query Parameters Ordering and Sorting
?order-by=populatrity&sorted-as=desc ?order-by=first-name&sorted-as=asc
Filtering ?filter-by= Etc…
Ordering, Sorting and Fitering
![Page 48: How RESTful Is Your REST?](https://reader031.vdocuments.us/reader031/viewer/2022012922/5563a3a9d8b42a2d538b541f/html5/thumbnails/48.jpg)
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
Views
![Page 49: How RESTful Is Your REST?](https://reader031.vdocuments.us/reader031/viewer/2022012922/5563a3a9d8b42a2d538b541f/html5/thumbnails/49.jpg)
Legacy Clients
![Page 50: How RESTful Is Your REST?](https://reader031.vdocuments.us/reader031/viewer/2022012922/5563a3a9d8b42a2d538b541f/html5/thumbnails/50.jpg)
Older Clients Only support GET and POST HTTP Methods
Use ?method=put
Legacy Clients
![Page 51: How RESTful Is Your REST?](https://reader031.vdocuments.us/reader031/viewer/2022012922/5563a3a9d8b42a2d538b541f/html5/thumbnails/51.jpg)
Security
![Page 52: How RESTful Is Your REST?](https://reader031.vdocuments.us/reader031/viewer/2022012922/5563a3a9d8b42a2d538b541f/html5/thumbnails/52.jpg)
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
Security
![Page 53: How RESTful Is Your REST?](https://reader031.vdocuments.us/reader031/viewer/2022012922/5563a3a9d8b42a2d538b541f/html5/thumbnails/53.jpg)
Testing You API
![Page 54: How RESTful Is Your REST?](https://reader031.vdocuments.us/reader031/viewer/2022012922/5563a3a9d8b42a2d538b541f/html5/thumbnails/54.jpg)
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/
Testing
![Page 55: How RESTful Is Your REST?](https://reader031.vdocuments.us/reader031/viewer/2022012922/5563a3a9d8b42a2d538b541f/html5/thumbnails/55.jpg)
Versioning
![Page 56: How RESTful Is Your REST?](https://reader031.vdocuments.us/reader031/viewer/2022012922/5563a3a9d8b42a2d538b541f/html5/thumbnails/56.jpg)
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
Versioning
![Page 57: How RESTful Is Your REST?](https://reader031.vdocuments.us/reader031/viewer/2022012922/5563a3a9d8b42a2d538b541f/html5/thumbnails/57.jpg)
Documentation
![Page 58: How RESTful Is Your REST?](https://reader031.vdocuments.us/reader031/viewer/2022012922/5563a3a9d8b42a2d538b541f/html5/thumbnails/58.jpg)
What to document Endpoint Description Prerequisites Request Response
Documentation
![Page 59: How RESTful Is Your REST?](https://reader031.vdocuments.us/reader031/viewer/2022012922/5563a3a9d8b42a2d538b541f/html5/thumbnails/59.jpg)
What to document Use a mind map
Documentation
![Page 60: How RESTful Is Your REST?](https://reader031.vdocuments.us/reader031/viewer/2022012922/5563a3a9d8b42a2d538b541f/html5/thumbnails/60.jpg)
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
Documentation
![Page 61: How RESTful Is Your REST?](https://reader031.vdocuments.us/reader031/viewer/2022012922/5563a3a9d8b42a2d538b541f/html5/thumbnails/61.jpg)
How Restful Is REST?
![Page 62: How RESTful Is Your REST?](https://reader031.vdocuments.us/reader031/viewer/2022012922/5563a3a9d8b42a2d538b541f/html5/thumbnails/62.jpg)
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
How Restful Is Your REST?
![Page 63: How RESTful Is Your REST?](https://reader031.vdocuments.us/reader031/viewer/2022012922/5563a3a9d8b42a2d538b541f/html5/thumbnails/63.jpg)
Question?
![Page 64: How RESTful Is Your REST?](https://reader031.vdocuments.us/reader031/viewer/2022012922/5563a3a9d8b42a2d538b541f/html5/thumbnails/64.jpg)
Recommended Reading
![Page 65: How RESTful Is Your REST?](https://reader031.vdocuments.us/reader031/viewer/2022012922/5563a3a9d8b42a2d538b541f/html5/thumbnails/65.jpg)
Tack själv!
PolymathicCoder