JAX-RS. Developing RESTful APIs with Java

JAX RS
Developing RESTful Applications

JERRY KURIAN. OVER 20 YEARS EXPERIENCE.
TECHNOLOGY INNOVATOR & ENTREPRENEUR
Started coding with an Intel 486 machine more than 25
years back and enjoying it ever since. Developed using
VB, Pascal, C++, Java Enterprise and OSS, Scala,
Node JS and the saga continues. Started using Spring,
hibernate before it became hip. Started using Scala
when it was in its infancy. After spending 8 years working in various
software companies like Huawei Tech, Quidnunc
across UK, US, China and India, the
entrepreneurship bug bit in 2006 (before it was
hip!!). Built one of the pioneers in SMS social
network called CellZapp, I developed the
product on my own and sold it to marquee
customers like ESPN and Hungama Digital.
Recently launched a product in field informatics
www.isense-tech.co.in. Successfully launched
across 3 pilot customers and on track to sign up
more.
A family man with two kids, I am a passionate
weekend cricketer and an involved dad. I urge my
two sons to follow their dreams, which they do by
staying out of the conventional schooling system
and exploring their passion at a democratic free
school called BeMe. Check it out at
http://beme.org.in

REFERENCES
 RESTful Java with JAX-RS 2.0, 2nd Edition
 https://www.safaribooksonline.com/library/view/restful-
java-with/9781449361433/

WHY REST?
 Web is one of the most successful “app” out there
 The web has grown exponentially and shows no
sign of stopping
 All apps need to learn and adopt from the
underlying architectural principles of the web to be
able to grow similarly
 The set of these architectural principles is
called REpresentational State Transfer (REST)

REST PRINCIPLE
 Addressable resources
 The key abstraction of information and data in REST is a
resource, and each resource must be addressable via a URI
(Uniform Resource Identifier).
 A uniform, constrained interface
 Use a small set of well-defined methods to manipulate your
resources.
 Representation-oriented
 You interact with services using representations of that
service. For example, browsers need HTML, JavaScript
needs JSON.
 Communicate statelessly
 Stateless applications are easier to scale.
 Hypermedia As The Engine Of Application
State (HATEOAS
 Let your data formats drive state transitions in your
applications.

ADDRESSABILITY
 Addressability is the idea that every object and
resource in your system is reachable through a
unique identifier.
 For an SOA, the means to discover a service or
resource is a big problem and addressability
through an identifier is an ideal solution
 In the REST world, addressability is managed
through the use of URIs
 scheme://host:port/path?queryString#fragment

UNIFORM INTERFACE VIA HTTP
 REST isn’t protocol specific
 But REST over HTTP is the most common way in which
REST applications are developed
 There have been other specifications that have
enabled distributed application development over
web
 WS-* and SOAP have been most popular. It also used
HTTP but more as a transport later to bypass the
firewalls
 REST uses HTTP as a very rich application
protocol that provides multitude of interesting and
useful capabilities for application developers

HTTP
http://www.cs.brandeis.edu/~rshaull/cs146a/project2/proxy-diagram.png

HTTP - METHODS
http://www.bogotobogo.com/python/images/python_http_web_services/HttpRequest.png
Browsers are one of the most well known users of HTTP protocol. But
they generally restrict themselves to GET and POST methods

HTTP - METHODS
 GET
 GET is a read-only operation. It is used to query the server for specific
information. It is both an idempotent and safe operation
 PUT
 PUT requests that the server store the message body sent with the
request under the location provided in the HTTP message. It is usually
modelled as an insert or update. It is also idempotent.
 DELETE
 DELETE is used to remove resources. It is idempotent as well.
 POST
 POST is the only non-idempotent and unsafe operation of HTTP. Each
POST method is allowed to modify the service in a unique way.
 HEAD
 HEAD is exactly like GET except that instead of returning a response
body, it returns only a response code and any headers associated with
the request.
 OPTIONS
 OPTIONS is used to request information about the communication
options of the resource you are interested in.
Idempotent means that no matter how many times you apply the operation, the result is always the same

REPRESENTATION ORIENTATION
 With a GET operation, you receive a representation
of the current state of a resource.
 A PUT or POST passes a representation of the
resource to the server so that the underlying
resource’s state can change
 In a RESTful system, the complexity of the client-
server interaction is within the representations
being passed back and forth. These
representations could be XML, JSON, YAML, or
really any format you can come up with.

HATEOAS
 The final principle of REST is the idea of using
Hypermedia As The Engine Of Application State
(HATEOAS).
 Hypermedia and Hyperlinks compose complex sets
of information from disparate sources.
<order id="111">
<customer>http://customers.myintranet.com/customers/32133</customer>
<order-entries>
<order-entry>
<quantity>5</quantity>
<product>http://products.myintranet.com/products/111</product>

DEVELOPING A RESTFUL JAVA APP
 For a Java programmer, the ideal scenario is to
ensure they stick to Java as much as possible
 As with frameworks and specs like Hibernate and
JPA, which bridges the Relational database world
with Java world, we need a way to do REST
programming using mainly Java constructs
 The steps to developing RESTful application are as
follows

STEPS TO DEVELOPING RESTFUL APPS
Define object
model
Model the URIs
Define
representation
format
Assign HTTP
methods

DEFINE OBJECT MODEL
 Developing enterprise applications often start with
defining its object model
 The object model defined for an application can be
used to define the various resources in our RESTful
application too
 Consider a typical Order entry system.
 Each order in the system represents a single
transaction or purchase and is associated with a
particular customer. Orders are made up of one or more
line items. Line items represent the type and number of
each product purchased.

OBJECT MODEL
 Based on the system description the object model
could be

MODEL THE URIS
 Java addresses a class or an entity via its package
and class name
 This format is well known within a JVM for a class
to access another class
 How do you make a Java class representing a
resource be known and accessible over the web?
 The answer lies in providing a URI for the java
based resources

URIS
 In our object model, we will be interacting
with Orders, Customers, and Products
 We can make these resources addressable as
follows
 /orders
 /orders/{id}
 /products
 /products/{id}
 /customers
 /customers/{id}

DEFINE REPRESENTATIONAL DATA FORMAT
 Within JVM, two objects talk to each other through
the state of the object or by serializing/de-serializing
object over the wire
 How can the state of a Java object be made known
to a client over the web?
 The representation of the state of a resource is one
of the most important things to do in a RESTful
application
 XML and JSON are two of the most popular way to
represent the resource states

XML BASED REPRESENTATION
Read or update operation

XML BASED REPRESENTATION
Create Operation

ASSIGNING HTTP METHODS
 The URIs defined earlier are a means to access as
well as perform operations on the resources
 A client typically would want to perform CRUD
operations on the resources
 To obtain all the products, you would typically
define GET method on the URI
 GET /products HTTP/1.1
 To limit the number of products returned, we can
pass the limiting parameters as query parameters
 GET /products?startIndex=0&size=5 HTTP/1.1

HTTP METHODS
 To obtain an individual product, the GET operation
would be defined as
 /products/{id}
 GET /products/233 HTTP/1.1
 To create a new product, use the PUT operation
 PUT /products/664 HTTP/1.1
 Drawback of using PUT is that the client is expected to
generate the ID of the new resource
 POST can also be used to create a new resource

HTTP METHODS
 Updating a resource can be achieved via a PUT
method
 To delete a resource, use the DELETE method
 DELETE /orders/233
 Cancellation of a resource is also update of a state
and can be achieved through DELETE with specific
query parameter
 DELETE /orders/233?cancel=true

OPERATIONS ON RESOURCES
 We might need to perform operations on resources
that do not strictly result in update of resource
states
 Eg of an operation would be purging of a resources,
which ultimately updates states of multiple
resources
 We can model operations as sub-resources and
trigger a POST operation
 POST /orders/purge HTTP/1.1
 The sub-resource URI can be further extended to
add interfaces as desired

DEVELOP A SAMPLE RESTFUL APPLICATION

FIRST APPLICATION
 Create the model class
 Define service
 Define Path and parameters
 Create the Application class
 Deploy
 Test Using Browser

JAX RS ANNOTATIONS FOR HTTP METHODS
 As seen in the examples, the JAX-RS API defines
support for various HTTP methods through
annotations
 The annotations supported are
 @javax.ws.rs.GET
 @javax.ws.rs.PUT
 @javax.ws.rs.POST
 @javax.ws.rs.HEAD
 @javax.ws.rs.DELETE

BINDING URIS
 The resources need to be addressed in a way that
is accessible over the web
 The path to the resource is annotated using
 @javax.ws.rs.Path
 For a Java class to be eligible to receive any HTTP
requests, the class must be annotated with at least
the @Path("/") expression
 The value of the @Path annotation is an expression
that denotes a relative URI to the context root of
your JAX-RS application

BINDING OPERATIONS
 @Path can also be applied to the java operations
 The URI matching pattern is a concatenation of the
class’s @Path expression and that of the method’s
 The URI pattern for getUnpaidOrders() would be
the relative URI /orders/unpaid

@PATH EXPRESSIONS
 @Path annotations support complex expressions
 /customers/200 will match the path for method
getCustomer. While /customers/foo-bar will match
following

REGULAR EXPRESSIONS
 The .+ is a regular expression that will match any
stream of characters after /customers
 The getAddress() method has a more specific
expression. Will map any characters
after/customers that ends with /address. The GET
/customers/foo/bar/address request would route to
the getAddress() method

SUBRESOURCE LOCATORS
 JAX-RS also allows you to dynamically dispatch requests
yourself through subresource locators
 Subresource locators are Java methods annotated
with @Path, without HTTP method annotation
 This returns a JAX-RS annotated service which dispatches
the remaining request
 Dispatches URI pattern /customers/{database}-
db/{customerId}

ACQUIRING DATA
 Every service requires a way to acquire data being
sent by the client and respond appropriately
 As seen earlier, the Jax RS services are normal
classes with operations being implemented using
the methods
 There is a need to ensure that data passed by the
client is receive by the appropriate methods
 Jax RS provides various annotations that bind to
input data and makes it available to methods

@PATHPARAM
 @PathParam allows you to inject the value of named
URI path parameters that were defined
in @Path expressions

MATRIX PARAMS
 There are times when you would want to pass an
input attribute via the path of the URI instead of
using the query params.
 Such params passed via the pat are called Matrix
Params
 Example. GET /cars/mercedes/e55;color=black/2006
 In the example, the attribute color is passed as a
matrix parameter

MATRIX PARAM USING @PATH AND
PATHSEGMENT

USING @MATRIXPARAM
 JAX-RS specification allows you to inject matrix
parameter values directly through
the @javax.ws.rs.MatrixParam annotation

USING THE QUERY STRING - @QUERYPARAM
 Generally attributes to a web resources are passed
using the Query String of the HTTP protocol
 The @javax.ws.rs.QueryParam annotation allows
you to inject individual URI query parameters into
your Java parameter
 GET /customers?start=0&size=10

INJECTING VIA FORM ELEMENT -
@FORMPARAM
 The @javax.ws.rs.FormParam annotation is used
to access application/x-www-form-url encoded
request bodies

@HEADERPARAM
 The @javax.ws.rs.HeaderParam annotation is used
to inject HTTP request header values.
 You could access the HTTP Referer header using
the @HeaderParam annotation

RAW HEADERS
 In case you need access to all the headers passed
in by the request, then it can be accessed via
HttpHeaders object set via @Context

@COOKIEPARAMS
 HTTP is stateless, but many applications might
require a state to be maintained
 Maintaining states is accomplished via tools like
 Sessions
 Cookies
 If a client app stores info in a cookie then it is also
responsible to send the data via request headers
 @CookieParams annotation allows service to
access data

AUTOMATIC TYPE CONVERSION
 Although, data sent via HTTP is usually represented as
String, the java method can receive the data in specific
type
 JAX-RS converts String into desired type as long as the
type conversion matches following criteria
1. The desired type is a primitive value
2. The desired type is a Java class with a constructor that
takes a single String as input
3. The desired type is a java class that has a static method
named valueOf() that takes a single String argument and
returns an instance of the class
4. It is a java.util.List<T>, java.util.Set<T>,
or java.util.SortedSet<T>, where T is a type that satisfies
criteria 2 or 3

COLLECTION OF PARAMETERS
 The client can pass a parameter multiple times, in
case there are multiple values to the parameter
 GET /customers?orderBy=last&orderBy=first
 JAX-RS provider represents these two parameters
as a java.util.List and injects this list
with one @QueryParam annotation

DEFAULT VALUE
 Many times the client may not have value for a
specific param and may not pass it
 This makes the value null. The null value may
cause problems to the service
 A default value can be set in such cases

ENCODED VALUES
 By default, JAX-RS decodes the input values
before converting them into Java types
 If you wish to make use of the raw encoded values,
then it is possible via @Encoded annotation

WRITING RESTFUL CLIENTS
 One of the major challenges in working with a
REST application is writing a client app
 Most of the annotations defined earlier are for
creating a RESTful service
 For writing clients, there are two options
 Develop client app using java.net.URL or Apache HTTP
Client
 Use JAX-RS API Client API, which makes working with
Jax RS much simpler

USING JERSEY FOR DEVELOPING CLIENT
 The Jersey based implementation can be used for
writing JAX-RS 2 clients
 Add the following dependency in pom.xml to make
use of the library
<dependencies>
<dependency>
<groupId>org.glassfish.jersey.core</groupId>
<artifactId>jersey-client</artifactId>
<version>2.23.2</version>
</dependency>
</dependencies>

CREATING A CLIENT
 API provides a class called javax.ws.rs.client.Client
which represents a JAX-RS client
 Create a new Client object using ClientBuilder
 Client client = ClientBuilder.newClient();
 Create the invocation target
 WebTarget target =
client.target("http://localhost:8080/SecondApp/services/c
ustomers/eg;color=black/2000");
 Send a GET request
 Response response = target.request().get();
 Analyze the response
 response.readEntity(String.class)
 Close the resources
 response.close()
 client.close()

WEBTARGET
 The WebTarget interface represents a specific URI
you want to invoke on.
 Some of the important methods it provides are

WEBTARGET
 Request invoker can be obtained from the
Webtarget via its request methods
 Invocation.Builder allows setting up of different
types of headers

NEED FOR CONTENT TRANSFORMATION
 Aim of a Java developer is to deal with Java object
as much as possible
 RESTful services often represent data in the form
of XML or JSON
 There is a need to seamlessly convert from the raw
XML or JSON format to Java object format so that
the developers can handle it easily

BUILT-IN CONTENT MARSHALLING
 StreamingOutput is a simple callback interface
that you implement when you want to do raw
streaming of response bodies

READING DATA
 For reading request message bodies, you can use
a raw InputStream or Reader for inputting any
media type

RECEIVING OR RETURNING FILES
 Instances of java.io.File can also be used for input
and output of any media type.

JAXB
 JAXB is a specification defined to map Java
classes to XML
 JAX-RS has built in support for JAXB

JAXB JAX-RS HANDLERS
 JAX-RS spec is required to marshall and un-
marshall JAXB objects

CUSTOM MARSHALLING
 In case where there is no direct support for
marshalling and unmarshalling of JAXB objects,
JAX-RS supports creating custom marshallers
 The interface to be implemented are
 MessageBodyWriter
 MessageBodyReader

IMPLEMENTING A MESSAGEBODYREADER
 An implementation needs to be annotated with
@Provider and @Consumes

PASSING OBJECTS FROM CLIENT
 JAX-RS client implementation environment may not
have in-built support for JAXB transformation
 In such cases it is required that the
MessageBodyReader and MessageBodyWriter is
implemented
 To make the class usable, it needs to be registered
with the WebTarget
 WebTarget target =
client.target("http://localhost:8080/SecondApp/services/
customers").register(CustomerReader.class).register
(CustomerWriter.class)

SERVER RESPONSES AND EXCEPTIONS

SUCCESSFUL RESPONSES
 Successful HTTP response code numbers range
from 200 to 399
 If a service returns null or empty body, then the
response code will be 204, “No Content”

ERROR RESPONSE
 Standard HTTP error response code numbers
range from 400 to 599
 If the client provides a URI that is not found then
the response code will be 404, “Not Found,”
 If a client requests text/html response for a
resource URI that is not returning anything then the
status code will be 406, “Not Acceptable,
 If the client invokes an HTTP method on a valid URI
to which no JAX-RS resource method is bound, the
JAX-RS runtime will send an error code of 405,
“Method Not Allowed.”
 Example, issuing PUT request to a resource that
supports only POST

COMPLEX RESPONSE
 For the cases where you need to control the
response, your JAX-RS resource methods can
return instances of javax.ws.rs.core.Response
 A ResponseBuilder can be used to construct a
Response

EXCEPTION HANDLING
 Errors can be reported to a client either by creating
and returning the appropriate Response object or
by throwing an exception
 JAX-RS provides
the javax.ws.rs.WebApplicationException. This can
be thrown by application code and automatically
processed by JAX-RS
 A Response object can be set in the exception
object which will be returned by JAX-RS service to
the client
 If there is no Response object set then the server
returns 500, “Internal Server Error,”

SECURING APPLICATIONS
 Authentication
 Authentication is about validating the identity of a client
that is trying to access your services.
 Authorization
 Authorization is about deciding whether or not a certain
user is allowed to access and invoke on a specific URI
 Encryption
 Sensitive data should be protected with cryptographic
services like SSL

BASIC AUTHENTICATION
 Basic Authentication is the simplest protocol available
for performing authentication over HTTP
 It involves sending a Base 64–encoded username and
password within a request header to the server
 If invoking a secure resource
 GET /customers/333 HTTP/1.1
 Pass Base 64 encoded username and password in
header username:password
 This has to be passed in every request
 Prone to hostile interception

AUTHORIZATION
 While authentication is about establishing and
verifying user identity, authorization is about
permissions.
 Authorization requires users to have one or more
roles
 Roles need to be assigned permissions to perform
operations

AUTHORIZATION USING JAX-RS
 Authentication and Authorization in JAX-RS can be
enabled either using web.xml or via Annotations
 JAX-RS defines following annotations
 @RolesAllowed – Lists the roles that are allowed
access
 @DenyAll – Denies access to all roles
 @PermitAll – Allows all roles

ENABLING AUTHORIZATION
 For the server to check for authorization, you need
to register certain interceptors
 The interceptors are specific to the implementation
 Jboss Resteasy expects you to register a
@Provider that is a PreProcessInterceptor
 The Pre-Processor should be registered with the
Application

THE WEB PARADIGM
 The Internet is commonly referred to as “the Web”
because information is connected together through
a series of hyperlinks embedded within HTML
documents
 The architectural principle that describes linking
and form submission is called HATEOAS
 HATEOAS stands for Hypermedia As The Engine
Of Application State

IMPLEMENTING HATEOAS
 Most XML-based RESTful applications use syntax
from the Atom Syndication Format as a means to
implement HATEOAS

ATOM LINKS
 Atom links have some key attributes
 rel
 It is the logical, simple name used to reference the link
 href
 This is the URL you can traverse in order to get new
information or change the state of your application.
 type
 This is the exchanged media type of the resource the
URL points to
 hreflang
 Represents the language the data format is translated
into.

HATEOAS AND JAX-RS
 HATEOAS is to be defined by the application, so
JAX-RS restricts itself to some helper methods to
construct the links

BUILD FROM PATH
 Given a path, the builder can help create a URI
 This would result in a URI
 http://example.com/customers/333?param=value

BUILD FROM RESOURCE
 Given a REST resource, you can build a URI

CACHING
 Caching is one of the most powerful technique to
improve performance
 Any service that provides static unchanging data is
an obvious candidate for caching
 Browser knows when to cache using the response
header called Expires

JAX-RS AND CACHING
 JAX-RS services can specify expires header using
Response

CACHECONTROL
 JAX-RS also provides a CacheControl class to
control the cache settings

CONCURRENCY
 In a highly concurrent RESTful application, care
should be taken that the a resource is not getting
updated with invalid data
 This can happen if a client has obtained a resource
with a particular state and before making the
update, some other client updates the data
 This problem can be overcome using conditional
PUT or POST

CONDITIONAL UPDATE
 A client receives a GET response with its Etag and
Last-Modified headers set
 When performing conditional PUT or POST, the
request should have If-Match or If-Unmodified-
Since header

CONDITIONAL UPDATE WITH JAX-RS
 To do conditional updates with JAX-RS, you use
the Request.evaluatePreconditions() method

CONNEG
 Clients set an Accept request header that is a
comma-delimited list of preferred formats.
 The client is asking the server for /stuff formatted in
either XML or JSON. It can also specify wildcards
 If the server is unable to provide the desired
format, it will respond with a status code of 406,
“Not Acceptable.”

JAX-RS AND CONNEG
 JAX-RS does method dispatching based on the
ACCEPT header values
 JAX-RS can pick one of these methods based on
what is in the Accept header

JAXB FOR CONNEG
 You can implement one Java method that can
service both formats
 The method would return representation as per the
ACCEPT header

EJB
 Java EE requires that EJB containers support
integration with JAX-RS
 When manually registering your resources via
your Application class, you must register the bean
class of the EJB via
the Application.getClasses() method.

EXAMPLE
 Create an app with following features
 Create a Product (Only allowed for Admin)
 Place an Order.
 Order Can include multiple Products
 View Pending Order (Only allowed for Admin)
 List All Customers
 Also return the list of orders as HATEOAS

JAX-RS. Developing RESTful APIs with Java

More Related Content

What's hot (20)

Similar to JAX-RS. Developing RESTful APIs with Java (20)

Recently uploaded (20)

JAX-RS. Developing RESTful APIs with Java