Define resource methods for RESTful applications

Define resource methods for RESTful applications

Overview

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

Clients use HTTP methods to perform certain operations. Unlike other distributed systems where unique interfaces are defined by each system, RESTful systems 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.
(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

Example web.xml file:
<servlet>
    ...
    ...
    <init-param>
        <param-name>propertiesLocation</param-name>
        <param-value>/WEB-INF/my_wink.properties</param-value>
    </init-param>
</servlet>
Example WEB-INF/my_wink.properties:
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. Make sure 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()      {
         ...
Define resource methods
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:port/context_root/servlet_path/bookstore/books

...by 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 URL...
http://host:port/context_root/servlet_path/bookstore/books/isbn_number

...by 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.
Avoid trouble: Do 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.gotcha
Results

You have defined valid operations for the resources.

Related tasks

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