Address Book Sample Application Guide

Version 1.0.0

Overview

The Address Book sample is an example of a RESTful service that stores/retrieves/removes/updates address book entries. Additionally, a client interface, written with DOJO, is provided to manipulate and view the address book.

AddressBook Resource

The path to the AddressBook resource is declared by the @Path annotation.

package com.ibm.rest.sample;

import java.util.Iterator;
import java.util.List;

import javax.ws.rs.Consumes;
import javax.ws.rs.DELETE;
import javax.ws.rs.FormParam;
import javax.ws.rs.GET;
import javax.ws.rs.POST;
import javax.ws.rs.PUT;
import javax.ws.rs.Path;
import javax.ws.rs.PathParam;
import javax.ws.rs.Produces;
import javax.ws.rs.QueryParam;

@Path(value = "/addresses")
public class AddressBook {

The AddressBook has seven methods of interest:

  1. This method maps to incoming GET requests whose request path is of the form '/addresses'

    @GET
@Produces(value = { "text/xml", "application/json" })
public AddressList getAddresses()

  2. This method maps to incoming POST requests whose request path is of the form '/addresses' and the Content-Type is "application/x-www-form-urlencoded". The information to create a new address instance is contained in the posted form.

    @POST
@Consumes(value = "application/x-www-form-urlencoded")
public void createAddress(
@FormParam(value = "entryName") String entryName, 
@FormParam(value = "zipCode") String zipCode, 
@FormParam(value = "streetAddress") String streetAddress, 
@FormParam(value = "city") String city, 
@FormParam(value = "state") String state, 
@FormParam(value = "country") String country)

  3. This method maps to incoming POST requests whose request path is of the form '/addresses' and the Content-Type is "text/xml". The information to create a new address instance is contained in the posted xml.

    @POST
@Consumes(value="text/xml")
public void addAddress(Address address)

  4. This method maps to incoming DELETE requests. The request path will be of the form '/addresses/{address_entry_name}'

    @DELETE
@Consumes(value = { "text/xml", "application/x-www-form-urlencoded" })
@Path(("/{entryName}"))
public void removeAddress(@PathParam(value = "entryName") String entryName)

  5. This method maps to incoming PUT requests whose request path is of the form '/addresses'. The information to update an address instance is contained in the query string.

    @PUT
@Consumes(value = { "text/xml", "application/x-www-form-urlencoded" })
public void updateAddress(
    @QueryParam(value = "entryName") String entryName, 
    @QueryParam(value = "zipCode") String zipCode, 
    @QueryParam(value = "streetAddress") String streetAddress, 
    @QueryParam(value = "city") String city, 
    @QueryParam(value = "state") String state, 
    @QueryParam(value = "country") String country)

  6. This method maps to incoming GET requests to search for an address instance. The request path will be of the form '/addresses/search/{search_string}'

    @GET
@Path(value="/search/{searchstring}")
@Consumes(value = { "text/xml", "application/x-www-form-urlencoded" })
@Produces(value = { "text/xml", "application/json"})
public AddressList search(@PathParam(value="searchstring") String searchString)

  7. This method maps to incoming requests, other than DELETE requests, whose request path is of the form '/addresses/{address_entry_name}'.

    @Path("/{entryName}")
public Address getAddress(@PathParam(value = "entryName")

    This method will delegate requests to the Address subresource. The Address subresource has a single method to serve GET requests:

    @GET
@Consumes(value = { "text/xml", "application/x-www-form-urlencoded" })
@Produces(value = { "text/xml", "application/json" })
public Address get()

Here's a brief summary of the resource:

Table 1. URI Overview
HTTP Method URI Input Type(s) Output Type(s) Note(s)
GET /addresses */* text/xml, application/json Get all addresses
POST /addresses application/x-www-form-urlencoded n/a Add a new address
POST /addresses text/xml n/a Add a new address
DELETE /addresses/{entryName} text/xml, application/x-www-form-urlencoded n/a Remove the specified address
PUT /addresses text/xml, application/x-www-form-urlencoded n/a Update an existing address
GET /addresses/search/{searchString} text/xml, application/x-www-form-urlencoded text/xml, application/json Get addresses whose entry matches 'searchString'
GET /addresses/{entryName} text/xml, application/x-www-form-urlencoded text/xml, application/json Delegate to GET on Address class, retrieve specified address

Address Book Client

The address book client presents a web interface that allows you to manipulate the Address Book Resource:

Installing/Running

  1. Install the 'addressBook_server.war' in a web container and assign a context root of '/rest' to the WAR.
  2. Install the 'addressBook_client.war' in a web container and assign a context root of your choosing.
  3. Navigate to http://{yourhost}:{yourport}/{client_context_root}/addressBook.html.
  4. Use the client interface to add, remove, update, or search for entries in the Address Book

Alternative cURL based commands for accessing the server