Chapter 3. Your First JAX-RS Service
The first two chapters of this topic focused on the theory of REST and designing the REST-
ful interface for a simple ecommerce order entry system. Now it's time to implement a part
of our system in the Java language.
Writing RESTful services in Java has been possible for years with the servlet API. If you
have written a web application in Java, you are probably already very familiar with servlets.
Servlets bring you very close to the HTTP protocol and require a lot of boilerplate code to
move information to and from an HTTP request. In 2008, a new specification called JAX-RS
was defined to simplify RESTful service implementation.
JAX-RS is a framework that focuses on applying Java annotations to plain Java objects. It
has annotations to bind specific URI patterns and HTTP operations to individual methods of
your Java class. It has parameter injection annotations so that you can easily pull in informa-
tion from the HTTP request. It has message body readers and writers that allow you to de-
couple data format marshalling and unmarshalling from your Java data objects. It has excep-
tion mappers that can map an application-thrown exception to an HTTP response code and
message. Finally, it has some nice facilities for HTTP content negotiation.
This chapter gives a brief introduction to writing a JAX-RS service. You'll find that getting it
up and running is fairly simple.
Developing a JAX-RS RESTful Service
Let's start by implementing one of the resources of the order entry system we defined in
date Customers . To do this, we will need to implement two Java classes. One class will be
used to represent actual Customers . The other will be our JAX-RS service.
Customer: The Data Class
First, we will need a Java class to represent customers in our system. We will name this class
Customer . Customer is a simple Java class that defines eight properties: id , firstName ,
lastName , street , city , state , zip , and country . Properties are attributes that can be ac-
cessed via the class's fields or through public set and get methods. A Java class that follows
this pattern is also called a Java bean :
package com . restfully . shop . domain ;