We will now start creating the RESTful web service for the auction application. We need to decide

1. What our resources will be
2. How we will address those resources
3. What the actions on those resources will be

For the first question, we have already jumped the gun a bit, and decided to model two classes of resource: items, and bids. These correspond to the two tables in the database. An item has a unique ID, a title, a description, a reserve price, and an expiry date. A bid has a unique ID, a bidder name, an item ID, a value, and a submission timestamp.

To address these resources, we will use a hierarchy which reflects the relational structure in the database. The service will be configured to live at:

http://localhost:8080/auction

Below this URL, we will have a resource representing the collection of all items:

http://localhost:8080/auction/item

A specific item can be referenced from that collection by appending the item’s unique ID:

http://localhost:8080/auction/item/1729

Finally, an individual item will have a collection representing the bids for it:

http://localhost:8080/auction/item/1729/bid

The last question is most easily answered. We need to be able to perform CRUD (Create, Read, Update, Delete) operations on the resources we have just defined. These map naturally to the HTTP actions POST, GET, PUT and DELETE, respectively.

• A GET operation will simply read the resource data and return it.

• A PUT operation on a resource will update it.

• A DELETE operation on a resource will remove it.

• A POST operation to a container (i.e. /auction/item or /auction/item/1729/bid) will create a new item in that container.

It would be unusual to see alternative semantics for these actions in a RESTful application.

We need to set up a new servlet in Tomcat to manage all of the URLs starting with http://localhost:8080/auction/. Create a directory in $CATALINA_HOME/webapps called auction, and a set of directories under that:

(In Linux)

mkdir $CATALINA_HOME/webapps/auction
mkdir $CATALINA_HOME/webapps/auction/WEB-INF
mkdir $CATALINA_HOME/webapps/auction/WEB-INF/classes
mkdir $CATALINA_HOME/webapps/auction/WEB-INF/lib

(In Windows)

mkdir %CATALINA_HOME%\webapps\auction
mkdir %CATALINA_HOME%\webapps\auction\WEB-INF
mkdir %CATALINA_HOME%\webapps\auction\WEB-INF\classes
mkdir %CATALINA_HOME%\webapps\auction\WEB-INF\lib

Create a web.xml file in $CATALINA_HOME/webapps/auction/WEB-INF:

<web-app>
  <servlet>
    <servlet-name>RestfulAuction</servlet-name>
    <servlet-class>AuctionServer</servlet-class>
  </servlet>
  
  <servlet-mapping>
    <servlet-name>RestfulAuction</servlet-name>
    <url-pattern>/</url-pattern>
  </servlet-mapping>
</web-app>

Copy the hsqldb/lib/hsqldb.jar file into the lib directory of your servlet. This should complete the necessary setup and configuration for your servlet. Continue on to the next section, where we will write the code for handling the GET verb.