Tutorial 2 - REST

2008-11-25

The purpose of this tutorial is to introduce RESTful web services. As the support for REST in Axis2 is somewhat limited (all the POST, PUT, GET, and DELETE are supported, but the databindings are cumbersome), we will in this tutorial use the JSR311 specification (JAX-RS Java API for RESTful Web Services), or more specifically, an implementation called RESTlets. During the tutorial, a teacher will be present to help with any practical issues that may arise. If you finish the tutorial ahead of time, you are recommended to get started on assignment 2. This tutorial is non-mandatory and your work on it will not be graded.

  1. Download RESTlets from here.
  2. Unzip the downloaded file into some directory, let us call the created directory RESTLETS_HOME.
  3. Download the sample service from here.
  4. Set the environment variable RESTLETS_LIB to $RESTLETS_HOME/lib
  5. Compile the sample service: 'ant'
  6. Start the sample service (embedded HTTP server): './server.sh'
  7. Try the sample clients {post,put,get,delete}.sh. A typical session is outlined below. Here, we create three items, list all available items, update the description of an item and inspect the result. Next, we delete an item, and finally, inspect the updated list of items.
    • ./post.sh item1 "A description of item1"
    • ./post.sh item2 "A somewhat more detailed description of item 2"
    • ./post.sh item3 "Yet another item"
    • ./get.sh
    • ./put.sh item2 "An updated description of item2"
    • ./get.sh item2
    • ./delete.sh item1
    • ./get.sh
  8. In the server terminal, you will see the HTTP command that correspond to these requests, and the respective responses.
  9. Also note that this service can be accessed through a standard web browser, take a look at e.g., http://localhost:8182/items
  10. Familiarize yourself with the sample service. Note how we define the resource types (ItemResource.java, ItemsResource.java) of the service. Observe how the FirstResourceApplication specifies a router to forward incoming requests to the correct resource implementation. Also note how FirstResourceMain.java launches the embedded HTTP server.
  11. Implement a simple service that manages mailing lists. Each mailing list has a name, and contains one or more email addresses. The following four step process can be applied when creating a RESTful interface:
    1. Define the resource types, including the data they contain and what their URIs should look like.
    2. Decide how to represent the resources in the system, XML is one, but no means the only choice.
    3. Decide which methods (of POST, PUT, GET, and DELETE) that are applicable to each resource type, and how the service-side implementation of these should look like.
    4. Define what HTTP status codes are applicable for the operations. Although the RESTlet framework hides the detail of these, a complete list of HTTP return codes is a useful part of the documentation of your service, and allows client developers to know what return codes to test for.
  12. Embed your new mailing list service into a servlet, and deploy that servlet in tomcat. In this scenario, tomcat replaces the embedded HTTP server. Here are some guidelines for tomcat deployment.