Introduction to RESTful Web Services 09/2012 Wei Li
Dec 05, 2014
Introduction to RESTful Web Services
09/2012
Wei Li
Agenda
• RESTful in General
• URI Design
• Java Implementation
• Others
• Test
• Demonstration
RESTful in General
In a Nutshell
• RESTful is about resources
• RESTful is about how to represent the resource in different ways
• RESTful is about how to manipulate the resource
Define REST
• REST stands for Representational State Transfer
• An architecture style for designing networked applications
Define REST
• REST offers a simple, interoperable, and flexible way of writing web services that can be very different than the RPC mechanisms like CORBA and WS-*
RESTful Is Not
• A protocol
• A standard
• A replacement for SOAP
RESTful Architectural Principles
• Addressable resources
• A uniform, constrained interface
• Representation oriented
• Stateless communicate
• Hypermedia As The Engine Of Application State (HATEOAS)
Resources
• The key abstraction of information and data in REST
• Each resource must be addressable via a URI (Uniform Resource Identifier)
• Everything can be a resource
Addressability
• Every object and resource in the system should be reachable through a unique identifier
• Managed through the use of URIs
Uniform and Constrained Interface
• Don’t have an “action” parameter in URI
• Use only the methods of HTTP for the web services
• HTTP has a small fixed set of operational methods. Each method has a specific purpose and meaning
Representation Oriented
• The user interacts with services using representations of that service
• A resource referenced by one URI can have different formats. – HTML (for browsers)
– XML (for application)
– JSON (for JavaScript)
– Excel spreadsheet
– Image
Stateless Communication
• No client session data stored on the server
• If there are needs for session-specific data, it should be held and maintained by the client and transferred to the server with each request as needed
• A service layer that does not have to maintain client sessions is much easier to scale
RESTful and HTTP
• REST isn't protocol specific
• However when talking about REST, people usually mean REST over HTTP
• Benefits of using HTTP for RESTful services:
Familiarity
Interoperability
Interoperability
REST Triangle
Source: http://en.wikipedia.org/wiki/File:Resttriangle.svg
HTTP Methods
• GET
• PUT
• DELETE
• POST
• HEAD
• OPTIONS
CRUD Operation Mapped to HTTP Methods in RESTful
OPERATION HTTP METHOD
Create POST
Read GET
Update PUT
Delete DELETE
HTTP Response Code
• 200 OK
• 201 Created
• 202 Accepted
• 204 Success
• 301 Moved Permanently
• 302 Found
• 303 See Other
• 304 Not Modified
• 500 Internal Error
• 503 Service Unavailable
HTTP Response Code
• 401 Unauthorized
• 403 Forbidden
• 404 Not Found
• 405 Method Not Allowed
• 409 Conflict
• 411 Length Required
• 413 Entity Too Long
• 415 Unsupported Media Type
Create a Resource
Source: Rest in Practice
Read a Resource
Source: Rest in Practice
Update a Resource
Source: Rest in Practice
Delete a Resource
Source: Rest in Practice
URI Design
URI
• Human meaningful
• Hierarchical
• Nouns
• No verbs
URI Examples
• http://localhost:9999/restapi/books – GET – get all books
– POST – add a new book
• http://localhost:9999/restapi/books/id – GET – get book whose id is provided
– PUT – update the book whose id is provided
– DELETE – delete the book whose is provided
URI Examples
• Twitter REST API v1.1 example: – https://dev.twitter.com/docs/api/1.1
Content Negotiation
Content Negotiation and URI
• http://localhost:9999/restapi/books/id.xml
• http://localhost:9999/restapi/books/id.json
• http://localhost:9999/restapi/books/id.pdf
Content Negotiation and URI
• https://cwiki.apache.org/WINK/jax-rs-content-negotiation.html
Java Implementation
JSR-311
• POJO based
• HTTP centric
• Format independence
• Container independence
• Inclusion in Java EE
JSR-311 Annotations
JSR 311 Annotations
Available Java Frameworks
• Jersey
• CXF
• Wink
• RESTEasy
Others
WADL
• The Web Application Description Language
• A machine-readable XML description of HTTP-based web applications (typically RESTful web services).
WADL
• Example (using Jersey implementation)
http://localhost:9999/restapi/application.wadl
Versioning
• Put the version in URI
http://localhost:9999/restapi/v2.0/books
Versioning
• put the version in the Accept Header of the request
http://stackoverflow.com/questions/389169/best-practices-for-api-versioning/6750376#6750376
Security
• HTTPS (encrypt channel)
• Web ACL
• Others (more advanced)
Error Handling
• Use standard error message format as response
• Use Non-200 response codes
HTTP/1.1 400 Bad Request
Content-Type: application/xml;charset=UTF-8
Link: http://server/error/someexplanation
<error>
<message>You have made an invalid request...
</message>
</error>
Demonstration
• A simple one page web application http://mybooks.cloudfoundry.com/books.html
• Restful web service is implemented using Jersey
• Client consumes the service through JQUERY AJAX API and render the JSON data
Test
Test RESTful Web Services
• Using cURL
Test RESTful Web Services
• Using cURL
Test RESTful Web Services
• Using cURL
Test RESTful Web Services
• Using SOAPUI
Test RESTful Web Services
• Using SOAPUI
Test RESTful Web Services
• Using SOAPUI
Test RESTful Web Services
• Using SOAPUI
Test RESTful Web Services
• Using SOAPUI
Reference
• http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm