The Top-Level Resource in Jersey

In RESTful Web Services, the authors define three types of resources exposed by a web service:

  1. Predefined one-off resources for especially important aspects of the application
  2. A resource for every object exposed through the service
  3. Resources representing the results of algorithms applied to the data set

#2 is probably what you think of first when you hear “RESTful web service”.  It’s basic CRUDRuby on Rails was designed to make it super easy to expose these types of resources.  If you have a restaurants table in your databse it gets exposed at  Create a new restuarant using POST /restaurants.  View restaurant info at GET /restaurants/{restaurantId}.  Modify a restaurant using PUT /restaurants/{restaurantId}.  Flush a restaurant down the toilet using DELETE /restaurants/{restaurantId}.

#3 is a bit less common but still familiar. is Google’s resource for documents about “restful web services”.  It’s the result of using Google’s search algorithms to find relevant documents.

#1 can be used for several different purposes, one of which is to provide a top-level entry point into your web service.  What you choose to put in the representation of the resource at depends on your service.  It could simply provide a way to get to another resource, like does (it gives you a search form).  Or it could give you some relevant account info, like (it lists your S3 buckets).  If you’re using XHTML as your representation format, it could provide some documentation about how to use your web service and provide various entry points (ie links) into it.

Using Jersey, it’s incredibly simple to create the top-level resource:

public class TopLevelResource
    public String get()
        return "<html><body>This is your top-level resource</body></html>";

That’s all there is to it!  The @Path(“/”) annotation makes this resource the top-level resource.  Of course you can add handlers for methods other than GET, but GET should always be used to provide some information about the entire web service.


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s