Annotations for processing HTTP request methods @GET @PUT @POST @DELETE @HEAD @OPTIONS

 

Annotations for processing HTTP request methods

In general, RESTful web services communicate over HTTP with the standard HTTP verbs (also known as method types) such as GET, PUT, POST, DELETE, HEAD, and OPTIONS.

@GET

A RESTful system uses the HTTP GET method type for retrieving the resources referenced in the URI path. The @javax.ws.rs.GET annotation designates the method of a resource class to respond to the HTTP GET requests.

The following code snippet illustrates the use of the @GET annotation to make a method respond to the HTTP GET request type. In this example, the REST URI for accessing the findAllDepartments() method may look like /departments. The complete URI path may take the http://host:port/<context-root>/<application-path>/departments URI pattern:

//imports removed for brevity 
@Path("departments") 
public class DepartmentService { 
  @GET 
  @Produces(MediaType.APPLICATION_JSON) 
  public List<Department> findAllDepartments() { 
    //Find all departments from the data store 
    List<Department> departments = findAllDepartmentsFromDB(); 
    return departments; 
  } 
  //Other methods removed for brevity 
}

@PUT

The HTTP PUT method is used for updating or creating the resource pointed by the URI. The @javax.ws.rs.PUT annotation designates the method of a resource class to respond to the HTTP PUT requests. The PUT request generally has a message body carrying the payload. The value of the payload could be any valid internet media type, such as the JSON object, XML structure, plain text, HTML content, or binary stream. When a request reaches a server, the framework intercepts the request and directs it to the appropriate method that matches the URI path and the HTTP method type. The request payload will be mapped to the method parameter as appropriate by the framework.

The following code snippet shows how you can use the @PUT annotation to designate the editDepartment() method to respond to the HTTP PUT request. The payload present in the message body will be converted and copied to the department parameter by the framework:

@PUT 
@Path("{id}") 
@Consumes(MediaType.APPLICATION_JSON) 
public void editDepartment(@PathParam("id") Short id,  
  Department department) { 
  //Updates department entity to data store 
  updateDepartmentEntity(id, department); 
} 

@POST

The HTTP POST method posts data to the server. Typically, this method type is used for creating a resource. The @javax.ws.rs.POST annotation designates the method of a resource class to respond to the HTTP POST requests.

The following code snippet shows how you can use the @POST annotation to designate the createDepartment() method to respond to the HTTP POST request. The payload present in the message body will be converted and copied to the department parameter by the framework:

@POST 
public void createDepartment(Department department) { 
  //Create department entity in data store 
  createDepartmentEntity(department); 
} 

@DELETE

The HTTP DELETE method deletes the resource pointed by the URI. The @javax.ws.rs.DELETE annotation designates the method of a resource class to respond to the HTTP DELETE requests.

The following code snippet shows how you can use the @DELETE annotation to designate the removeDepartment() method to respond to the HTTP DELETE request. The department ID is passed as the path variable in this example:

@DELETE 
@Path("{id}") 
public void removeDepartment(@PathParam("id") Short id) { 
  //remove department entity from data store 
  removeDepartmentEntity(id); 
} 

@HEAD

The @javax.ws.rs.HEAD annotation designates a method to respond to the HTTP HEADrequests. The HEAD method is the same as the GET request, but it only transfers the status line along with the header section (without the response body) to the client. This method is useful for retrieving the metadata present in the response headers, without having to retrieve the message body from the server. You can use this method to check whether a URI pointing to a resource is active or to check the content size by using the Content-Length response header field.

The JAX-RS runtime will offer the default implementations for the HEAD method type if the REST resource is missing explicit implementation. The default implementation provided by the runtime for the HEAD method will call the method designated for the GET request type, ignoring the response entity returned by the method.

@OPTIONS

The @javax.ws.rs.OPTIONS annotation designates a method to respond to the HTTP OPTIONS requests. This method is useful for obtaining a list of HTTP methods allowed for a resource.

The JAX-RS runtime will offer a default implementation for the OPTIONS method type if the REST resource is missing an explicit implementation. The default implementation offered by the runtime sets the Allow response header to all the HTTP method types supported by the resource.