-->

+

Search Tips   |   Advanced Search

Define the URI patterns for resources in RESTful applications

Representational State Transfer (REST) services are based on manipulating resources. Resources for RESTful services are addressable via URLs.

Identify the resources in the application to expose as a RESTful service.

URL specify the location of a resource. Interaction between the server and client is based on issuing HTTP operations to URLs. Defining URL patterns is important because URLs often have a long lifetime so that clients can directly address a resource long after the resource is initially discovered.

URLs are typically used when you enter addresses to web browsers, such as...

...or...

Although URLs are not required to be understandable by users, RESTful services that provide logical URLs in understandable patterns enable client application developers to work efficiently.

RESTful clients use URLs to manipulate resources. Each resource must have its own unique URL. Some URL patterns have a collection path with a unique identifier appended. For example, we can use...

...as the collection resource URL,...

...as a unique book resource URL, and we can use...

...to retrieve a collection resource describing ISBN123 authors.

The application developer must carefully consider the granularity of URLs because it can affect usage of the application and performance. For example, we can include the author information of a book as part of the book resource or we can define the author information as a unique resource with its own URL referenced in the book resource. Depending on the reuse of resources, it might be more efficient to define a separate resource for the author information referenced in a hyperlink of the book resource for cases when the author writes a different book.

After an initial URL is given to a client, subsequent related requests are discoverable by parsing the current resource. In the book example, a GET request to...

...retrieves a list of book URLs that can include...

Because systems rely on resources being available, URLs typically have longevity. Because HTTP has built-in status codes for redirection, such as the 301 moved permanently code and the 307 temporarily redirected code, users and clients with caches often reuse previously discovered URLs first. We can additionally consider including a version identifier in the URL pattern, such as...

Add @Path annotations to the Java class files or the Java methods to define the relative URL of the resource. We can use JAX-RS subresource locators and subresource methods to define resources. Use parameters, such as the path parameter or matrix parameter, in the URL to identify the resource.

The value in the @Path annotation defines the relative part of the full URL to the resource. The base URL is derived from the domain, port, application module context root, and any URL pattern mappings in web.xml of the application module. For example, if the domain is www.example.com, the port is 9060, the module context root is example, the servlet URL pattern is store/*, and the value of the @Path annotation is

The full URL is:

  1. Identify the types of resources in the application. Suppose that we have two types of resources, a BooksCollection and an individual Book object which have the following class definitions: 
    public class BooksCollection  {
    public BooksCollection()      {
        /* no argument constructor */
    }
 }
 public class Book  {
    public Book(String ISBN)      {
        /* This constructor has an argument that will be annotated with a JAX-RS annotation.
         See the JAX-RS specification for information on valid constructors. */
    }
}
    As defined in the JAX-RS specification, by default, resource instances are created per request. For the JAX-RS runtime environment to create a resource instance, have either a constructor with no argument or a constructor with only JAX-RS annotated parameters present.

  2. Add a @javax.ws.rs.Path annotation to each resource class. For each @javax.ws.rs.Path annotation, set the value as the part of the URL after the base URL of the application. 
    /*
 * BooksCollection.java
 * This Java class represents the books collection URL at /bookstore/books.
 */
@javax.ws.rs.Path("/bookstore/books/")
public class BooksCollection  {
 }
    After completing the application, we can use the resource by visiting...

      http://host:port/context_root/servlet_path/bookstore/books

    For this URL, specify the context root value as the part of the URL after the context module. Specify the servlet path as any URL patterns in web.xml, if it exists.

  3. Optional. Determine if a resource needs to use part of the URL as a parameter. If a resource needs to use part of the URL as a parameter, such as an identifier, we can use the @javax.ws.rs.Path annotation with a regular expression. We can then add a @javax.ws.rs.PathParam annotation in either the resource constructor or the resource method. 
    /*
 * Book.java represents individual books.
 */
@javax.ws.rs.Path("/bookstore/books/{bookID}")
public class Book  {
   public Book(@javax.ws.rs.PathParam("bookID") String ISBN)     {
    }
}
    When an HTTP request is made to...

      http://host:port/context_root/servlet_path/bookstore/books/ISBN_number

    ... a Book instance is created with ISBN_number passed in to the ISBN parameter of the constructor.

    For more information about other possible parameters, read about defining parameters for requests to resources in RESTful applications.

  4. Create the javax.ws.rs.core.Application subclass to define to the JAX-RS runtime environment which classes are part of the JAX-RS application. The resource classes are returned in the getClasses() method; for example: 
    public class BookApplication extends javax.ws.rs.core.Application  {
    public Set<Class<?>> getClasses()      {
        Set<Class<?>> classes = new HashSet<Class<?>>();
        classes.add(BooksCollection.class);
        classes.add(Book.class);
        return classes;
    }
}

    By defining the javax.ws.rs.core.Application subclass, classes returned from its methods are registered to the JAX-RS runtime environment. When configuring web.xml, specify the javax.ws.rs.core.Application subclass as a parameter to the servlet or filter. For more information, read about configuring web.xml for JAX-RS applications.


Results

You have created a URL to identify the resources for your RESTful service. By considering issues with URL patterns early in the application design, the RESTful service increases its usability and value over an extended time.


What to do next

The resource at the defined URL exists. However, the resource does not yet have any methods to handle HTTP method actions such as GET, POST, PUT, or DELETE. See the defining resource methods for RESTful applications to learn more about defining capabilities of resources using supported HTTP methods.


Related concepts

  • Overview of Java API for RESTful Web Services (JAX-RS)


    Related tasks

  • Define the resources in RESTful applications
  • Define resource methods for RESTful applications
  • Define the HTTP headers and response codes for RESTful applications
  • Define parameters for request representations to resources in RESTful applications
  • Define media types for resources in RESTful applications
  • Configure web.xml for JAX-RS servlets
  • Configure web.xml for JAX-RS filters