© 2010 VMware Inc. All rights reserved

Building RESTful Web Services with JavaVassil Popovski (vpopovski@vmware.com) Staff Engineer, R&D

VMware, Inc.

10/07/2010

2

Agenda REST Principles and examples Java (JAX-RS) and REST Live Demo JAX-RS Advanced concepts

3

What is REST?

4

5

What is REST ? (now seriously)

Representational State Transfer Introduced in 2000 by Roy Fielding:

• in his PhD thesis (chapter 5) http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm

• Captured his interpretation of the WWW architecture

Architectural style for distributed system such as World Wide Web• Note: REST is *not* a standard, just a set of principles

Positioned as an alternative to WS-* implementations

6

What is REST ? (now seriously)

7

REST Principles (RESTful systems)

Everything is a resource• Examples: Customer, Locations, Item, List of users

Resources have identifiers• Examples: URIs for web

Uniform interfaces to access the resources• Examples: HTTP methods (GET, POST, PUT, DELETE, HEAD)

Resources have representations• Examples: XML, JSON, Binary

Link resources together• Hypermedia as the Engine of Application State (HATEOAS)

• Examples: Hyperlinks

1

2

3

4

5

9

Real life example

Bug tracking system (over simplified)• Bugs (summary, priority, user who reported it)

• Notes (description, user who created the note)

• Users (user name)

UML Notation:“whole-part” relationship (composition)“part” is exclusively owned by “whole”

UML Notation:One-way association

UML Notation:Generalization / inheritance

10

Real life example – resources and identifies

Resources:• User, Bug, Note,

• All users, All bugs, All notes for a particular bug

IdentifiersIdentifiers Notehttp://<host>/users All users

http://<host>/users/{userId} A particular user

http://<host>/bugs All bugs

http://<host>/bugs/{bugId} A particular bug

http://<host>/bugs/{bugId}/notes All notes for a particular bug

http://<host>/bugs/{bugId}/notes/{noteId} A particular note for a particular bug

1 Everything is a resource

2 Resources have identifiers

11

Uniform interfaces (in the context of REST)

HTTP verbs (CRUD interfaces)HTTP verb Meaning Safe? Idempotent? Cacheable?

POST Create*

GET Retrieve

PUT Update*

DELETE Delete

f(f(x)) = f(x)Does not cause side effects

(*) POST and PUT may also have other meaningsPOST – can be used for partial updates and also to add something to a resource (PASTE AFTER)PUT – can be used to create if sending the full content of the specified resource and you know the URI of the resource (PASTE OVER)

12

Real life example – uniform interfaces

Operation DescriptionGET http://<host>/users List all users

POST http://<host>/users Creates a new user

GET http://<host>/users/345 Retrieves a particular user

PUT http://<host>/users/345 Modifies a particular user

DELETE http://<host>/users/345 Deletes a particular user

Operation DescriptionGET http://<host>/bugs/234/notes List all notes for bug 234

POST http://<host>/bugs/234/notes Creates a new note for bug 234

[GET | PUT | DELETE] .../bugs/234/notes/34 [retrieves | modifies | deletes] note 34 in bug 234

3 Uniform interfaces to access the resources

13

Real life example – representations and linking resources XML representation for note:

JSON representation for bug:

GET http://localhost:9000/bugs/1/notes/1 Content-type: application/xml<Note href=“http://localhost:9000/bugs/1/notes/1"> <description>It is really broken</description> <owner>http://localhost:9000/users/1</owner></Note>

POST http://localhost:9000/bugs Content-type: application/json{ "Bug" : { "priority" : "P1", "reporter" : "http://localhost:9000/users/1", "summary" : "Something is wrong" }}

4 Resources have representations

5 Link resources together

Note: the client can request different representations using “Accept” http header

Note: the client declares what representation it sends to server with “Content-type” http header

14

Java and REST

15

JAX-RS: Java API for RESTful Web Services

JSR 311 (https://jsr311.dev.java.net/)• Current version of JAX-RS spec is 1.1

• The spec is “readable”!

• Roy Fielding is an expert group member for this JSR

• javax.ws.rs.*

JAX-RS in 1 sentence:• JAX-RS = POJOs + Annotations

JAX-RS capabilities:• Dispatch URIs to specific classes and methods that can handle requests

• Methods deal with POJOs (nicely integrates with JAXB)

• Allows to map HTTP requests to method invocations

• URI manipulation functionality

16

JAX-RS implementations

Jersey (reference implementation) Apache CXF (the one used in the demo) Apache Wink eXo RESTEasy Restlet Triaxrs

17

JAX-RS key concepts

Resource classes• Java classes that have at least one method annotated with @Path or a request method designator

(@GET, @PUT, @POST, @DELETE)

• Lifecycle: • By default a new resource class instance is created for each request

• The JSR does not restrict other implementation specific lifecycles

Resource methods• A public method of a resource class annotated with a request method designator (@GET, @PUT,

@POST, @DELETE, @OPTIONS, @HEAD)

Provider classes• Classes annotated with @Provider and implementing one or more JAX-RS interfaces:

• MessageBodyReader/MessageBodyWriter

• ExceptionMapper

• ContextResolver

• Lifecycle: • By default single instance of each provider class is instantiated for each JAX-RS application

• The JSR does not restrict other implementation specific lifecycles

18

JAX-RS annotations (most commonly used)

Annotation Target Description@Path Class or Method Relative path for a resource

@Consumes@Produces

Class or Method List of media types that can be consumed / produced

@GET@POST@PUT@DELETE@OPTIONS@HEAD

Method HTTP verb handled by the annotated method

@PathParam Parameter (also field, POJO method)

Value that can be extracted from URI

@Context Parameter (also field, POJO method)

Inject contextual information – UriInfo, HttpHeaders, Request, ContextResolver, etc.

19

JAX-RS complete example

@Path("/users")

public class UserHandler {

@GET

@Path("{id}")

@Produces("application/xml”)

public JaxbUser getUser(@PathParam("id") long id) {

...

}

20

JAX-RS complete example

@Path("/users")

public class UserHandler {

@GET

@Path("{id}")

@Produces("application/xml”)

public JaxbUser getUser(@PathParam("id") long id) {

...

}

Base URI path to resource

21

JAX-RS complete example

@Path("/users")

public class UserHandler {

@GET

@Path("{id}")

@Produces("application/xml”)

public JaxbUser getUser(@PathParam("id") long id) {

...

}

The HTTP method for getUser() method

22

JAX-RS complete example

@Path("/users")

public class UserHandler {

@GET

@Path("{id}")

@Produces("application/xml”)

public JaxbUser getUser(@PathParam("id") long id) {

...

}

URI path segment/parameter

23

JAX-RS complete example

@Path("/users")

public class UserHandler {

@GET

@Path("{id}")

@Produces("application/xml”)

public JaxbUser getUser(@PathParam("id") long id) {

...

}

GET …/users/{id}

24

JAX-RS complete example

@Path("/users")

public class UserHandler {

@GET

@Path("{id}")

@Produces("application/xml”)

public JaxbUser getUser(@PathParam("id") long id) {

...

}

Returned Content-Type

25

JAX-RS complete example

@Path("/users")

public class UserHandler {

@GET

@Path("{id}")

@Produces("application/xml”)

public JaxbUser getUser(@PathParam("id") long id) {

...

}

Injects the value of URI segment into the id

parameter

26

JAX-RS complete example

@Path("/users")

public class UserHandler {

@GET

@Path("{id}")

@Produces("application/xml”)

public JaxbUser getUser(@PathParam("id") long id) {

...

}

GET http://localhost:9000/users/2Content-Type: application/xml

<?xml version="1.0" encoding="UTF-8"?><User> … </User>

27

28

Demoto wake you up…

29

Advanced topics

Regular expressions in @Path @*Params ExceptionMapper MessageBodyReader/MessageBodyWriter

30

@Path and regular expression mappings

@Path(path-expression)

"{" variable-name [ ":" regular-expression ] "}“

Examples• @Path("example2/{var:.+}") matches following:

• …/example2/a

• …/example2/a/b/c

• @Path("example3/{var:\\d+}") matches following:• …/example3/345

• …/example3/23

• @Path(“example4/{name}-{id}”) matches following:• …/example4/a-1• …/example4/a----1

31

@[Query|Header|Matrix|Cookie|Form]Param @QueryParam

• For example …/query?sorted=true@GET@Path("query")public String queryParamExample(@QueryParam(“sorted") String var) {return var;

}

@MartixParam• For example …/users;sorted=true

@HeaderParam• For example “Date” header

@CookieParam / @FormParam

@DefaultValue – can be used with any @*Param to specify the default value

32

Exception Mappers

package javax.ws.rs.ext

public interface ExceptionMapper<E extends Throwable> {

Response toResponse(E exception);

}

33

MessageBodyReader

MessageBodyReader MessageBodyWriter

package javax.ws.rs.ext

public interface MessageBodyReader<T> {

boolean isReadable(Class<?> type, Type genericType,

Annotation annotations[], MediaType mediaType);

T readFrom(Class<T> type, Type genericType,

Annotation annotations[], MediaType mediaType,

MultivaluedMap<String, String> httpHeaders,

InputStream entityStream) throws IOException, WebApplicationException;

}

34

MessageBodyWriter

package javax.ws.rs.ext

public interface MessageBodyWriter<T> {

boolean isWriteable(Class<?> type, Type genericType,

Annotation annotations[], MediaType mediaType);

long getSize(T t, Class<?> type, Type genericType, Annotation annotations[],

MediaType mediaType);

void writeTo(T t, Class<?> type, Type genericType, Annotation annotations[],

MediaType mediaType,

MultivaluedMap<String, Object> httpHeaders,

OutputStream entityStream) throws IOException, WebApplicationException;

}

35

JAX-RS features that were not covered PathSegment @Encoded @ApplicationPath Cookies Complex negotiation / Variant processing (javax.ws.rs.core.Variant): @OPTIONS, @HEAD, @HttpMethod SecurityContext CacheControl (+ Etags, conditional GET/PUT) Application (+ how to deploy in servlet container, EE6, EJB) Integration with Spring Security

36

Several other topics not covered

Restful java clients WADL REST support in Spring 3.0

37

Additional materials

Apache CXF (JAX-RS part): http://cxf.apache.org/docs/jax-rs.html RESTEasy users guide:

http://docs.jboss.org/resteasy/docs/1.1.GA/userguide/pdf/RESTEasy_Reference_Guide.pdf

WizTools REST Client: http://code.google.com/p/rest-client/

38