Network Deployment (Distributed operating systems), v8.0 > Develop and deploying applications > Develop web services - RESTful services > Plan JAX-RS web 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 by 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 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 given URL. It is also idempotent.

The HTTP POST method is often used when 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, you 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 sub-resource method and a sub-resource locator method that have an @Path annotation with the same value in the same resource class, the sub-resource 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 sub-resource locators being used if no sub-resource 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


Procedure

  1. 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 you 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;
    }
}
    When 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.
  2. 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, 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.


Results

You 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

+

Search Tips   |   Advanced Search