Define resource methods for RESTful applications

Define resource methods for RESTful applications

Individual resources can define their capabilities using supported HTTP methods. In Representational State Transfer (REST) services, the supported methods are GET, PUT, DELETE, and POST. All operations are typically conducted using one of the predefined HTTP methods with a resource.

Understand the predefined HTTP methods and their known attributes. Some HTTP methods are meant to be safe, meaning that issuing the request does not change the resource, or idempotent, meaning that multiple invocations of the operation do not change the result. While HTTP methods are defined to have certain attributes, the service implementation follows the definitions. See the HTTP method definitions information to learn more about the common set of methods for HTTP.

Clients use HTTP methods to perform certain operations. Unlike other distributed systems where unique interfaces are defined by each system, RESTful systems that are based on HTTP mainly rely on predefined methods. The four most common methods are GET, PUT, DELETE, and POST. Resources are not required to permit all HTTP methods for all clients.

The HTTP GET method retrieves a resource representation. It is safe and idempotent. Repeated GET requests do not change any resources.

The HTTP PUT method is often used to update resources or to create a new entity at a known URL. When a resource must be updated or created, an HTTP PUT method is issued at the resource URL with the new resource data as the request entity, also known as the message body. The HTTP PUT method is idempotent so multiple identical PUT requests with the same entity to the same URL yields the same result as if only one PUT request was issued. This method assumes that no other relevant requests were made.

The HTTP DELETE method removes a resource at a specific URL.

The HTTP POST method is often used while creating a resource in a collection when the final resource URL is not known. For instance, an administrator issues a POST request to a /users collection resource that creates a user with a unique ID such as 1234567890. The unique ID is then used as part of the URL path to describe the new user resource, such as /users/1234567790. It is not safe and is not idempotent. In this case, the multiple POST requests to the /users collection can continue creating a new unique ID and adding this new ID to the users collection even if the user has the same information.

Because most RESTful services use well-known HTTP methods that provide expected results, we can more easily create clients. RESTful service developers can take advantage of the expected behaviors of HTTP methods. Resource methods can also use parameters, such as path parameters, query parameters, or matrix parameters to identify the resource. Read about defining the use of parameters for request representations to resources to learn more.

(optional) If we have a subresource method and a subresource locator method that have an @Path annotation with the same value in the same resource class, the subresource locator is not considered when determining the method to invoke by default. This is in compliance with the JAX-RS specification.

Use the wink.searchPolicyContinuedSearch property with a value of true to modify this behavior. This results in subresource locators used if no subresource methods match the request.

To enable the property, include a properties file in the WEB-INF directory of the module that has the wink.searchPolicyContinuedSearch property and value specified. In the web.xml file of the application module, include an init-param element with the propertiesLocation value for the param-name element. The param-value element specifies the location of the properties file, for example, WEB-INF/my_wink.properties.

The following example illustrates the web.xml file:
<servlet>
    ...
    ...
    <init-param>
        <param-name>propertiesLocation</param-name>
        <param-value>/WEB-INF/my_wink.properties</param-value>
    </init-param>
</servlet>
The following example illustrates the WEB-INF/my_wink.properties properties file:
wink.searchPolicyContinuedSearch=true
In the following code example the request URL ends with sayhello but the request contains a POST instead of a GET, so an HTTP 405 Method Not Allowed error message is returned. Verify the HTTP method sent matches the method annotation to avoid the 405.
@javax.ws.rs.Path("helloworld")
public class SampleResource {

...

@javax.ws.rs.Path("sayhello")
@javax.ws.rs.GET
public String getHello() { ...
Tasks
Identify the types of resources in the application.
For each resource class, identify an existing method or create a method to invoke for each supported HTTP method. Methods that respond to HTTP requests are also known as resource methods. For each resource method in the resource class, annotate the Java method with a single JAX-RS HTTP method annotation such as @javax.ws.rs.GET, @javax.ws.rs.POST, @javax.ws.rs.DELETE or @javax.ws.rs.PUT. For example, if an HTTP GET method is supported by the BooksCollection class, then we can create and annotate a method like the following snippet:
@javax.ws.rs.Path("/bookstore/books/")
public class BooksCollection {
   @javax.ws.rs.GET
   public String getBooksCollection() {
       String str = /* Construct a String representation of the resource. */
       return str;
   }
}
Upon issuing an HTTP GET request to http://<host_name>:<port>/<context_root>/<servlet_path>/bookstore/books URL using a web browser or another HTTP client, the previous getBooksCollection() method is invoked.
Ensure that the resource supports the required HTTP methods.
Each resource typically has multiple resource methods; for example:
@javax.ws.rs.Path("/bookstore/books/{bookID}")
public class Book {
   /* This is a database key. */
   private String ISBN;

   public Book(@javax.ws.rs.PathParam("bookID") String ISBN) {
       this.ISBN = ISBN;
   }

   @javax.ws.rs.GET
   public String retrieveSpecificBookInformation() {
       /* This code retrieves a book resource based on the ISBN key. */
   }

   @javax.ws.rs.PUT
   public String updateBookInformation(String updatedBookInfo) {
       /* This code updates the book resource based on ISBN key and the entity (message body) sent
         in the request stored in updatedBookInfo. */
   }

   @javax.ws.rs.DELETE
   public void removeBook() {
       /* This code deletes a book resource based on ISBN key. */
   }
}
When issuing an HTTP GET request to the http://<host_name>:<port>/<context_root>/<servlet_path>/bookstore/books/<isbn_number> URL using a web browser or another HTTP client, the retrieveSpecificBookInformation() method is invoked. Sending an HTTP PUT request to the same URL invokes the updateBookInformation method and any content in the request message body is passed as the value of the updatedBookInfo object. Finally, sending an HTTP DELETE request to the same URL invokes the removeBook() method.
According to the JAX-RS specification, we must not put multiple HTTP method annotations, such as @javax.ws.rs.POST or @javax.ws.rs.PUT on the same resource method. Because HTTP methods have uniquely defined semantics, do not use a resource method for multiple HTTP methods.
We have defined valid operations for the resources.

Define the resources in RESTful applications
Define the HTTP headers and response codes for RESTful applications
Define the URI patterns for resources in RESTful applications
Define parameters for request representations to resources in RESTful applications
Define media types for resources in RESTful applications
HTTP method definitions