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

Books