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.

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: http://www.infoq.com/articles/rest-introduction 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 http://www.infoq.com/articles/rest-introduction

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* Give everything an ID Use standard methods Link things together Multiple representations 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: <prop self=" http://example.com/orders/101230 "> <customer ref=" http://example.com/customers/bar "> <product ref=" http://example.com/products/21034 "/> <amount value="1"/> </order>

Link Things Together 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

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

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 Building a Simple Service 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

Link Things Together 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 RESTful Design and API Elements Building a Simple Service Deployment Options Status

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 http://www.infoq.com/articles/rest-introduction

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/", "name":"Friendly Cat", "description":"This black and white colored cat is super friendly.", "id":"1", "imageurl":"http://localhost:8080/CatalogService/images/anthony.jpg"}, {"@uri":"http://host/catalog/resources/items/2/", "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 ":[ {"@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"}, {"@uri":"http://host/catalog/resources/items/2/", "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>

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 JAX-RS application packaged in WAR like a servlet For JAX-RS aware containers web.xml can point to ApplicationConfig subclass For non-JAX-RS aware containers web.xml points to implementation-specific Servlet ; and an init-param identifies the ApplicationConfig subclass Resource classes and providers can access Servlet request, context, config and response via injection

Java EE 6 Plans JAX-RS is part of Java EE 6 Applications deployed in a Java EE 6 Web container will have access to additional resources: Resources @Resources EJB @EJB ... Stateless session EJBs as resource classes More portable deployment with Servlet 3.0

Summary REST architecture is gaining popularity Simple, scalable and the infrastructure is already in place JAX-RS (JSR-311) provides a high level declarative programming model http://jersey.dev.java.net Jersey available 1.0 and 1.0.1: Glassfsh v2/v3 1.0: NetBeans 6.5

For More Information Official JSR Page http://jcp.org/en/jsr/detail?id=311 JSR Project http://jsr311.dev.java.net/ Reference Implementation http://jersey.dev.java.net/ Marc's Blog http://weblogs.java.net/blog/mhadley/ Paul's Blog http://blogs.sun.com/sandoz/ Jakub's Blog http://blogs.sun.com/japod/ Carol's Blog http://weblogs.java.net/blog/caroljmcdonald/

Presenter’s Name [email_address] Carol McDonald Java Architect http://weblogs.java.net/blog/caroljmcdonald/

RESTful Web Services with JAX-RS

More Related Content

RESTful Web Services with JAX-RS