How RESTful Is Your REST?
•Download as PPTX, PDF•
20 likes•8,339 views
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.
How RESTful Is Your REST?
- 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
- 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
- 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?
Editor's Notes
- http://translate.google.com/#sv/en/Trevligt%20att%20träffa%20dig%20svenska%20hackare!http://translate.google.com/#en/sv/I%20am%20happy%20to%20be%20here