RESTful Web Services with JAX-RS

REST Carol McDonald, Java Architect

Agenda

REST Primer

RESTful Design and API Elements

Building a Simple Service

Status

Q & A

REpresentational State Transfer

Get

http://www.depot.com/parts

Response XML data = REpresentational State Transfer

The URL identifies the resource

HTTP GET method operates on the resource

html page is transferred to the browser

REpresentational State transfer

The page ( application state ) is stored on the client (browser)

Click on the link (resource) in page ( hypermedia )

New state transfer occurs

REST architecture for the Web Web platforms Addressable Resources Web Container Addressable Resources Web Container

REST Tenets

Resources ( nouns )

Identified by a URI , For example:

http://www.parts-depot.com/parts

Methods ( verbs ) to manipulate the nouns

Small fixed set:

GET, PUT, POST, DELETE

Read, Update, Create, Delete

Representation of the Resource

data and state transferred between client and server

XML, JSON ...

Use verbs to exchange application state and representation

HTTP Example Request GET /music/artists/beatles/recordings HTTP/1.1 Host: media.example.com Accept: application/xml Response HTTP/1.1 200 OK Date: Tue, 08 May 2007 16:41:58 GMT Server: Apache/1.3.6 Content-Type: application/xml; charset=UTF-8 <?xml version="1.0"?> <recordings xmlns="…"> <recording>…</recording> … </recordings> Method Resource Representation State transfer

REST in Five Steps*

Give everything an ID

Use standard methods

Link things together

Multiple representations

Stateless communications

http://www.infoq.com/articles/rest-introduction

Uniform Interface

Give Every Thing an Id http://company.com/customers/123456 Resource Collection name Primary key http://company.com/customers/123456/orders/12 http://example.com/orders/2007/11 http://example.com/products?color=green URI is the id, Every resource has a URI

URIs identify :

items, collections of items, virtual and physical objects, or computation results.

REST in Five Steps*

Stateless communications

Uniform Interface

Use Standard HTTP Methods: GET = Read

GET to retrieve information

Should not modify anything

Cacheable

Example

GET /store/customers/123456

Use Standard HTTP Methods: POST = Create

POST to add new information

add the entity , append to the container resource

POST /store/customers

<customer>

<name>carol</name>

</customer>

Response

HTTP/1.1 201 Created

Location: http://store/customers/789

Use Standard HTTP Methods: PUT = Update

PUT to update information

Full entity create/replace used when you know the “ id ”

Example

PUT /store/customers/123456

<customer>

<name>jane</name>

</customer>

Use Standard HTTP Methods: DELETE

Remove (logical) an entity

Example

DELETE /store/customers/123456

Use Standard Methods:

Order Customer Mgmt Example

Use Standard Methods:

/orders

GET - list all orders

POST - submit a new order

/orders/{order-id}

GET - get an order representation

PUT - update an order

DELETE - cancel an order

/orders/average-sale

GET - calculate average sale

/customers

GET - list all customers

POST - create a new customer

/customers/{cust-id}

GET - get a customer representation

DELETE- remove a customer

/customers/{cust-id}/orders

GET - get the orders of a customer

Order Customer Mgmt Example

Use Standard HTTP Methods

HTTP Get, Head

Should not modify anything

Cache-able

With Correct use of Last-Modified and ETag

Idempotency:

PUT, DELETE, GET, HEAD can be repeated and the results are the same

REST in Five Steps*

Stateless communications * Inspired by Stefan Tilkov: http://www.innoq.com/blog/st/presentations/2008/2008-03-13-REST-Intro--QCon-London.pdf

Link Things Together

Representations contain links to other resources

Service provides links in response to the Client

Enables client to move the application from one state to the next by following a link

Representations contain links to other resources:

Representations contain links to other resources

Put a service in different states by following links and filling in forms

“ Hypermedia as the engine of application state”

HTML, XML, JSON, N3 can all be Hypermedia

Client is in charge

Service offers potential states

Service does not impose state transition order

REST in Five Steps*

Multiple Representations

Offer data in a variety of formats, for different needs

XML

JSON

(X)HTML

Support content negotiation

Accept header GET /foo Accept: application/json

URI-based GET / foo.json

content negotiation

Multiple Representations Content-type HTTP header Accept HTTP header Request GET /music/artists/beatles/recordings HTTP/1.1 Host: media.example.com Accept : application/xml Response HTTP/1.1 200 OK Date: Tue, 08 May 2007 16:41:58 GMT Server: Apache/1.3.6 Content-Type : application/xml; charset=UTF-8 <?xml version="1.0"?> <recordings xmlns="…"> <recording>…</recording> … </recordings> Format Representation

REST in Five Steps*

Stateless Communications

HTTP protocol is stateless

Everything required to process a request contained in the request

No client session on the server

Eliminates many failure conditions

application state kept on Client

Service responsible for resource state

Common Patterns: Container, Item Server in control of URI

Container – a collection of items

List catalog items: GET /catalog/items

Add item to container: POST /catalog/items

with item in request

URI of item returned in HTTP response header

e.g. http://host/ catalog/items/1

Update item: PUT /catalog/items/1

with updated item in request

Good example: Atom Publishing Protocol

Common Patterns: Map, Key, Value Client in control of URI

List key-value pairs : GET /map

Put new value to map: PUT /map/{key}

with entry in request

e.g. PUT /map/dir/contents.xml

Read value: GET /map/{key}

Update value: PUT /map/{key}

with updated value in request

Remove value: DELETE /map/{key}

Good example: Amazon S3

Key Benefits

Server side

Uniform Interface

Cacheable

Scalable

Easy failover

Client side

Easy to experiment in browser

Broad programming language support

Choice of data formats

bookmarkable

Agenda

REST Primer

RESTful Design and API Elements with JAX-RS

Status

Q & A

JAX-RS: Clear mapping to REST concepts

High level, Declarative

Uses @ annotation in POJOs

Jersey – reference implementation of JSR 311

Download it from http://jersey.dev.java.net

Comes with Glassfish, Java EE 6

Tools support in NetBeans

Four other open source implementations:

Apache CXF

JBoss RESTEasy

Restlet

Triaxrs

Give Everything an ID

“Thing” == resource class

POJO, No required interfaces

ID provided by @Path annotation

Relative to deployment context

Annotate class or “ sub-resource locator” method

http://host/ctx/orders/12 http://host/ctx/orders/12/customer @Path( "orders/{id}") public class OrderResource { @Path("customer") CustomerResource getCustomer(...) {...} }

Use Standard Methods

Annotate resource class methods with standard method

@GET , @PUT , @POST , @DELETE , @HEAD

annotations on parameters specify mapping from request data

Return value mapped to http response

@Path("orders/ {order_id} ") public class OrderResource { @GET Order getOrder( @PathParam (" order_id ") String id) { ... } }

Multiple Representations Static and dynamic content negotiation

Annotate methods or classes

@Produces matches Accepts header

@Consumes matches Content-Type header

@GET @Consumes("application/json") @Produces({"application/xml","application/json"}) String getOrder(@PathParam("order_id") String id) { ... }

Multiple Representations : JAX-RS consuming

Annotated method parameters extract client request information

@PathParam extracts information from the request URI

@QueryParam extracts information from the request URI query parameters

http://host/catalog/items/ 123 http://host/catalog/items/ ?start=0

Multiple Representations : JAX-RS consuming http://host/catalog/items/?start=0 http://host/catalog/items/123 @Path("/items/") @ConsumeMime(“application/xml”) public class ItemsResource { @GET ItemsConverter get( @QueryParam ("start") int start ) { ... } @Path( "{id}/" ) ItemResource getItemResource( @PathParam ("id")Long id ){ ... } }

Multiple Representations : Supported Types

JAX-RS can automatically (un)-marshall between HTTP request/response and Java types

“Out-of-the-box” support for the following

text/xml, application/xml, application/json – JAXB class

*/* – byte[]

text/* – String

application/x-www-form-urlencoded - MultivaluedMap<String, String>

response

Multiple Representations @Post @ConsumeMime(“application/x-www-form-urlencoded”) @ProduceMime(“application/xml”) public JAXBClass updateEmployee( MultivalueMap<String, String> form) { ... Converted to a map for accessing form's field converted to XML

Multiple Representations : producing a response Use Response class to build “created”response @Path(“/items”) class Items { @POST @ProduceMime(“application/xml”) Response create(Ent e) { // persist the new entry, create URI return Response.created ( uriInfo.getAbsolutePath(). resolve(uri+"/")).build(); } }

Uniform interface: HTTP request and response C: POST /items HTTP/1.1 C: Host: host.com C: Content-Type: application/xml C: Content-Length: 35 C: C: <item><name>dog</name></item> S: HTTP/1.1 201 Created S: Location: http://host.com/employees/1234 S: Content-Length: 0

Response Codes and Custom Responses

JAX-RS returns default response codes

GET returns 200 OK

PUT returns 201 CREATED

See

http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html

200 OK

201 Created

202 Accepted

203 Non-Authoritative Information

204 No Content

205 Reset Content

206 Partial Content

207 Multi-Status

226 IM Used

. . .

JAX-RS provides Response class @PUT public Response putUser( @PathParam(“id”) int id) { if (!id.equals(userid) ) return Response .status(409).entity( "userids differ").build();

JAX-RS provides Response class:

to specify response codes, to add onto the response

can construct more sophisticated return result

Can build responses for redirects, errors, ok, setting headers, etc

WebApplicationException Example @GET public Employee getEmployee( @PathParam(“id”) int id) { if (!doesEmployeeExist(id)) throw new WebApplicationException( new Throwable("Resource for " + uriInfo.getAbsolutePath() + " does not exist."), 404); Response: HTTP Status 404 -

Use it when the method has a return type

Simple error indicator

UriInfo provides information about the request URI and the route to the resource

UriBuilder provides facilities to easily build URIs for resources

@Context UriInfo info ; OrderResource r = ... UriBuilder b = info.getBaseUriBuilder(); URI u = b.path(OrderResource.class).build(r.id);

Statelessness: JAX-RS

The default component lifecycle is per-request

A new instance created for every request

Reduces concurrency issues

HTTP session life-cycle is not supported

On server side Developer must model state

As resource state in the representations

Agenda

REST Primer

Deployment Options

Status

Example RESTful Catalog

Example RESTful Catalog http://weblogs.java.net/blog/caroljmcdonald/archive/2008/08/a_restful_pet_c.html

Example RESTful Catalog Service Catalog Database Web container (GlassFish™) + REST API Browser (Firefox) HTTP

URIs and Methods:

/items

GET - list all items

POST – add item to catalog

/items/{id}

GET - get an item representation

PUT - update an item

DELETE – remove an item

Item Catalog Example

Methods

Java method name is not significant

The @HTTP method is the method

@Path(“/items”) class ItemsResource { @GET Items get() { ... } @POST Response create(Item) { ... } } class ItemResource { @GET Item get(...) { ... } @PUT void update(...) { ... } @DELETE void delete(...) { ... } }

RESTful Catalog

Dojo client, JAX-RS, JAXB, JPA

DB Registration Application JAX-RS class Dojo client JAXB class Entity Class ItemsConverter Item ItemsResource

Entity Classes

Use JPA to map/retrieve data from the database as entities

expose entities as RESTful resources

entity = resource identified by URL

http://host/catalog/items/123 public class Item { int id; String name; String descr; String url; } @Entity @Id Item ID NAME DESC URL

Converter Classes

JAXB to convert the domain objects (JPA entities ) into XML and/or JSON .

DB JAX-RS class Dojo client JAXB class Entity Class ItemsConverter Item ItemsResource

ItemConverter JAXB annotated @XmlRootElement(name = "item") public class ItemConverter { private Item entity; private URI uri; @XmlAttribute public URI getUri() { return uri; } @XmlElement public Long getId() { return (expandLevel > 0) ? entity.getId() : null; } ... }

XML <item uri="http://localhost/Web/resources/items/1/" > <description> black cat is nice</description> <id>1</id> <imagethumburl>/images/anth.jpg</imagethumburl> <name>not Friendly Cat</name> <price>307.10</price> <productid>feline01</productid> </item>

JSON

{

"@uri":"http://host/catalog/resources/items/1/",

"name":"Friendly Cat",

"description":"This black and white colored cat is super friendly.",

"id":"1",

"imageurl":" http://localhost:8080/CatalogService/images/anthony.jpg "

}

ItemsConverter JAXB annotated @XmlRootElement(name = "items") public class ItemsConverter { private Collection<ItemConverter> items; private URI uri; @XmlAttribute public URI getUri() { return uri; } @XmlElement public Collection<ItemConverter> getItem() { ... return items; } }

XML <?xml version="1.0" encoding="UTF-8"?> <items uri="http://localhost/Web/resources/items/"> <item uri="http://localhost/Web/resources/items/1/" > <description> black cat is nice</description> <id>1</id> <imagethumburl>/images/anth.jpg</imagethumburl> <name>not Friendly Cat</name> <price>307.10</price> <productid>feline01</productid> </item> <item . . . </item> </items>

JSON

{

"@uri":"http://host/catalog/resources/items/",

" item ":[

{"@uri":"http://host/catalog/resources/items/1/",

"id":"1",

"imageurl":"http://localhost:8080/CatalogService/images/anthony.jpg"},

"name":"Fluffy Cat",

"description":"A great pet for a hair stylist!

"id":"2",

"imageurl":"http://localhost:8080/CatalogService/images/bailey.jpg"}

]

}

Resource Classes

Items Resource retrieves updates a collection of Item entities

/items – URI for a list of Items

Item resource retrieves or updates one Item entity

/item/1 – URI for item 1

DB JAX-RS class Dojo client JAXB class Entity Class ItemsConverter Item ItemsResource

Get Items @Path("/items/") public class ItemsResource { @Context protected UriInfo uriInfo; @GET @Produces ("application/json") public ItemsConverter get(){ return new ItemsConverter( getEntities(), uriInfo.getAbsolutePath()); } Performs JPA Query, returns list of entities JAXB class responds with JSON responds to the URI http://host/catalog/items/ responds to HTTP GET

Get Item @Path("/items/") public class ItemsResource { @Path("{id}/") public ItemResource getItemResource( @PathParam ("id") Long id) { return new ItemResource (id, context); } } public class ItemResource { @GET @Produces ( "application/json") public ItemConverter get() { return new ItemConverter(getEntity(), context.getAbsolutePath(), expandLevel); } JAXB class http://host/catalog/items/123

Dojo Client

Use dojo.xhrGet to make HTTP method call to catalog service to get JSON items data:

{" items ":

{"@uri":"http://host/catalog/resources/items/",

" item ":[

"id":"1",

"imageurl":"http://localhost:8080/CatalogService/images/anthony.jpg"},

"name":"Fluffy Cat",

"description":"A great pet for a hair stylist!

"id":"2",

"imageurl":"http://localhost:8080/CatalogService/images/bailey.jpg"}

]

}

}

Dojo client index.html <button dojoType="dijit.form.Button" onclick=" next "> Next </button> <div id="grid" dojoType =" dojox.Grid " model =" model " structure =" layout " autoWidth="true" > http://weblogs.java.net/blog/caroljmcdonald/archive/2008/08/a_restful_pet_c.html Grid widget

Dojo client.js formatImage = function(value) { if (!value) return ' '; return "<img src='" + value + "'/>"; }; // Data Grid layout // A grid view is a group of columns var view1 = { cells: [ [ {name: 'Name', field: "name"}, {name: 'Description', field: "description"}, {name: 'Photo',field: "imagethumburl", formatter: formatImage , }, {name: 'Price',field: "price"} ] ] }; // a grid layout is an array of views. var layout = [ view1 ]; // the model= collection of objects to be displayed in the grid model = new dojox.grid.data.Objects(null,null);

RESTful Pet Catalog Web Service http://petstore/catalog/resources/items/ HTTP GET {"url":"http://store/catalog/item1", {"url":"http://store/catalog/item2"} Response JSON slide urls Server Client Addressable Resources Web Container

Dojo client.js // make request to the items web service function loadTable (page){ start = page * batchSize; var targetURL = "resources/items/?start="+ encodeURIComponent(start); dojo.xhrGet ({ url: targetURL , handleAs: "json", load: handleResponse , error: handleError }); } // Process the response from the items web service function handleResponse ( responseObject , ioArgs){ // set the model object with the returned items list model .setData( responseObject.items.item ); } function next() { page =page + 1; loadTable (page); } Performs HTTP GET on url catalog/items

Client & WADL

NetBeans IDE can generate JavaScript client stubs from a WADL or projects containing RESTful resources

NetBeans IDE exposes popular SaaS services using WADLs and can generate Java code to access them

Learn more at https://wadl.dev.java.net/

Example:

<application>

<resources base=" http://localhost:11109/CustomerDB/resources/ ">

<resource path="/items/">

<method name="GET">

<request>

<param default="0" type="xs:int" style="query" name="start"/>

<param default="10" type="xs:int" style="query" name="max"/>

</request>

<response>

<representation mediaType="application/xml"/>

</response>

</method>

</resource>

</resources>

.....

</application>

JavaFX Stage Scene Stage is the top level container window Scene is a drawing surface container that holds the scene graph nodes. content holds JavaFX graphical elements which define the graphical content of the application.

JavaFX Stage Scene // Application User Interface var stageContent: Node[]; stageContent = [bgImage, nextButton, backButton, titleText, thumbImageViewGroup, fullImageView ]; def stage = Stage { title: "Pet Catalog" width: 201 height: 201 scene : Scene { content : Group { content: bind stageContent } fill: Color.TRANSPARENT } } top level container window container holds the scene graph holds graphical elements

JavaFX Stage Scene var stageContent: Node[]; stageContent = [bgImage, nextButton, backButton, titleText, thumbImageViewGroup, fullImageView ]; def stage = Stage { title: "Pet Catalog" width: 201 height: 201 scene : Scene { content : Group { content: bind stageContent } fill: Color.TRANSPARENT } }

RESTful Pet Catalog Web Service http://petstore/catalog/resources/items/ HTTP GET Response XML items <item> <imageurl>http://host/catalog/images/anthony.jpg</imageurl> <name>Friendly Cat</name> <price>307.10</price> <productid>feline01</productid> </item> Server Client Addressable Resources Web Container

JavaFX HttpRequest function loadImageMetadata() { var start=page * 9; var request: HttpRequest = HttpRequest { location: " http://localhost:8080/catalog/resources/items/ " method: HttpRequest.GET onInput: function(input: java.io.InputStream) { var parser = PhotoPullParser{}; photos = parser.parse(input) ; } onDone: function() { updateImages() ; } } request.enqueue(); } Performs HTTP GET on url catalog/items

JavaFX HttpRequest public class PhotoPullParser { public function parse(input: InputStream): Photo[] { var photos: Photo[]; var photo: Photo; def parser = PullParser {input: input onEvent : function(event: Event) { if ( event.type == PullParser.START_ELEMENT ) { if(event.qname.name == " item " and event.level == 1) { photo = Photo { }; } } else if ( event.type == PullParser.END_ELEMENT ) { if( event.qname.name == " item " and event.level == 1) { insert photo into photos; } else if( event.qname.name == " imagethumburl " and event.level == 2) { photo.imagethumburl = event.text; } ... } } } parser.parse(); return photos; } <item> <imageurl>http://y.jpg</imageurl> <name>Friendly Cat</name> ... </item>

Agenda

REST Primer

Status

Q & A

Java SE

RuntimeDelegate used to create instances of a desired endpoint class

Application supplies configuration information

List of resource classes and providers as subclass of ApplicationConfig

Implementations can support any Java type

Jersey supports Grizzly (see below), LW HTTP server and JAX-WS Provider

ApplicationConfig config = ... RuntimeDelegate rd = RuntimeDelegate.getInstance(); Adapter a = rd.createEndpoint(config, Adapter.class); SelectorThread st = GrizzlyServerFactory.create( “ http://127.0.0.1:8084/”, a);

Servlet