Developing RESTful Services Using JAX-RS

Transcription

1 Developing RESTful Services Using JAX-RS Bibhas Bhattacharya CTO, Web Age Solutions Inc. April 2012.

2 Many Flavors of Services Web Services come in all shapes and sizes XML-based services (SOAP, XML-RPC, RSS / ATOM Feeds) HTTP services (REST, JSON, standard GET / POST) Other services (FTP, SMTP) While SOAP is the most common style of service, increasingly organizations are utilizing REST for certain scenarios REpresentational State Transfer (REST), first introduced by Roy Fielding (co-founder of the Apache Software Foundation and coauthor of HTTP and URI RFCs) Used extensively by Amazon, Google, Yahoo, Flickr, and others

3 Understanding REST REST applies the traditional, well-known architecture of the Web and HTTP to Web Services Extends the notion of a page as a resource to any entity as a resource for example, Orders, Customers, Price quote. Each URI uniquely points to a resource or a collection thereof. /orders/10025 Order number /trains/bom/del/ All trains from Mumbai to New Delhi on Leverages HTTP methods for manipulating entities PUT Creates a resource GET Retrieves a resource or collection of resources. DELETE Remove a representation of a resource. POST Updates a representation of a resource.

4 Understanding REST... Uses HTTP reply status code to indicate outcome of an operation. 200 or Success Invalid URI or unavailable resource General error Uses the Content-Type request and response header to indicate data format of request or response body. text/plain - Plain text, no format text/html text/xml, application/xml - XML application/json - JSON

5 Principles of RESTful Services Roy Fielding in his doctoral thesis tried to analyze the wild success of the web and how can some of its architecture principles be applied to any software. Thus RESTful services were born. There are three essential elements to any RESTful service Addressable resources A URI uniquely points to a resource or collection of resources. Uniform operations a small number of HTTP methods (GET, POST, PUT, DELETE) that work uniformly for all entities. Resource representation A representation is document in a certain format (XML, JSON etc.) that describes a resource. A consumer and provider of services should be able to negotiate the format. Stateless Services should be stateless. That is, a consumer should be able to complete a business task by issuing a single HTTP request.

6 Example: Catalog Service A RESTful service that manages online retail store product catalog. This service manages the catalog itself as a resource. Within that, there are sub-resources: Product Category Discount Promotions We will use this service to learn about the HTTP interaction patterns.

7 Create a New Product PUT /RESTWeb/catalogs/products HTTP/1.1 Content-type: text/xml Content-Length: 142 Request <?xml version="1.0" encoding="utf-8"?> <product> <price>125.99</price> <name>baseball bat</name> <code>1029</code> </product> Response HTTP/ Created Location: Content-Length: 0

8 Retrieve a Product Request GET /RESTWeb/catalogs/products/1029 HTTP/1.1 Accept: text/xml HTTP/ OK Content-Type: text/xml Content-Length: 137 Response <?xml version="1.0" encoding="utf-8" standalone="no"?> <product> <price>125.99</price> <name>baseball bat</name> <code>1029</code> </product>

9 Update a Product POST /RESTWeb/catalogs/products/1029 HTTP/1.1 Content-type: text/xml Content-Length: 144 Request <?xml version="1.0" encoding="utf-8"?> <product> <price>125.99</price> <name>baseball glove</name> <code>1029</code> </product> Response HTTP/ No Content Content-Length: 0

10 Delete a Product Request DELETE /RESTWeb/catalogs/products/1029 HTTP/1.1 Content-type: text/xml Accept: text/xml Response HTTP/ No Content Content-Length: 0

11 Introduction to JAX-RS JAX-RS (JSR 311) is the a specification for developing a RESTful service using Java EE. V2.0 will also include an API to consume RESTful services. Uses JAXB to map Java objects to XML or JSON. A resource class is created that represents a resource such as catalog and its sub-resources, such as, products. This facade class contains methods that a client can invoke by sending HTTP requests. These methods perform create, retrieve, update and delete operations on the associated resource and sub-resources. Annotations are used to configure the HTTP method, MIME type of data format and URI path associated with

12 The Resource Class //Manages the catalog resource and public class CatalogService {... } URI syntax: /RESTWeb/catalogs/products/1029 Web module context root + JAX-RS Servlet path + Resource path + Sub-resource path + Identifier (/RESTWeb) + (/*) + (/catalogs) + (/products)

13 The Entity public class Product { String code; String name; double price; } public String getcode() { return code; } public void setcode(string code) { this.code = code; } //Other getters and setters omitted

14 Retrieve a "application/xml", "text/xml"}) public Product findproduct(@pathparam("code") String code) { ProductDAO dao = new ProductDAO(); } return dao.findbycode(code);

15 Create @Consumes({"application/json", "application/xml", "text/xml"}) public Response addproduct(product p) { //Use DAO to add the product //... //Prepare the response UriBuilder ub = ui.getrequesturibuilder(); ub = ub.path(catalogservice.class, "findproduct"); URI producturi = ub.build(p.getcode()); } return Response.created(productURI).build();

16 Update @Consumes({"application/json", "application/xml", "text/xml"}) public void String code, Product p) { public void removeproduct(@pathparam("code") String code) { //... }

17 Content Negotiation A RESTful service can and should support multiple data formats, such as XML and JSON. XML is easier for full programming languages like Java and C#. JSON is easier for JavaScript. A client should specify its preference for data format using the Accept HTTP request header. In addition to data format, language and locale can also be negotiated. This will affect the language of textual data and price and date formatting.

18 Retrieving a JSON Representation Request Response GET /RESTWeb/catalog/product/1029 HTTP/1.1 Content-type: text/xml Accept: application/json HTTP/ OK Content-Type: application/json {"code":"1029","name":"baseball bat","price":125.99}

19 Sending a JSON Representation Request POST /RESTWeb/catalog/product/1029 HTTP/1.1 Content-type: application/json Content-Length: 52 {"code":"1029","name":"baseball bat","price":125.99} Response HTTP/ No Content Content-Length: 0

20 Summary REST is a simple and consistent way to provide access to enterprise data. The simplicity comes from leveraging the familiar HTTP protocol and not adding any extra new semantics on top of it. Before starting code, always spend extra time modeling the service: What are the resources and sub-resources? Should product be a resource on its own or a sub-resource of a catalog? Design the URI structure. Decide what HTTP method, and status code should be used for each operation. For more information on JAX-RS and RESTful design methodology, attend our course "WA2028 Mastering JAX-RS RESTful Web Services and AJAX Clients". Ask your Web Age sales contact today!