Define the URI patterns for resources in RESTful applications

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, and URLs are the primary way of achieving addressability in REST.

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

URLs are used to 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 http://www.ibm.com/ or http://www.example.com/bookstore/books/ISBN123. 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 http://www.example.com/bookstore/books as the collection resource URL, http://www.example.com/bookstore/books/ISBN123 as a unique book resource URL, and we can use http://www.example.com/bookstore/books/ISBN123/authors 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 http://www.example.com/bookstore/books/ retrieves a list of book URLs that can include http://www.example.com/bookstore/books/ISBN123.

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 http://www.example.com/bookstore/v2/books/ISBN123. Like the planning involved to define an interface using Java code, be sure to carefully choose your URL patterns because of expected longevity.

In Java API for RESTful Web Services (JAX-RS), we must add @Path annotations to the Java class files or the Java methods to define the relative URL of the resource. 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 your resource. The base URL is derived from the domain, port, application module context root, and any URL pattern mappings in the web.xml file 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 /bookstore/books. The full URL is: http://www.example.com:9060/example/store/bookstore/books.

Tasks
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, we must have either a constructor with no argument or a constructor with only JAX-RS annotated parameters present.
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_name>:<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 the web.xml file, if it exists.
(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_name>:<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.
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 the web.xml file, specify the javax.ws.rs.core.Application subclass as a parameter to the servlet or filter. For more information, read about configuring the web.xml file for JAX-RS applications.
We have created a URL to identify your resources for our 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:

Overview of IBM JAX-RS
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 the web.xml file for JAX-RS servlets
Configure the web.xml file for JAX-RS filters