Defining resource methods for RESTful applications
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.
Before you begin
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.
About this task
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, 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 you 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 that are 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.
<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. Make sure that 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() { ...
Procedure
Results
You have defined valid operations for the resources.