HTTP defines methods (sometimes referred to as verbs) to indicate the desired action to be performed on the target resource. JAX-RS uses five annotations for specifying the HTTP verb that can be used on a method (resource method):
javax.ws.rs.DELETE: The annotated Java method maps to a HTTP DELETE request. The HTTP DELETE request is used to delete the specified resource. This operation is idempotent.
javax.ws.rs.GET: The annotated Java method maps to a HTTP GET request. HTTP GET request is used to only retrieve resource data.
javax.ws.rs.POST: The annotated Java method maps to a HTTP POST request. HTTP POST request submits data to be processed (e.g., from an HTML form) to the identified resource. The data is included in the body of the request. This may result in the creation of a new resource or the updates of existing resources or both.
javax.ws.rs.PUT: The annotated Java method maps to a HTTP PUT request. In HTTP PUT request, the enclosed entity is stored under the supplied URI. If the URI refers to an already existing resource, it is modified; if the URI does not point to an existing resource, then the server can create the resource with that URI. PUT is idempotent, so if you PUT an object twice, it has no effect. If we name the resource to be created by ourselves (while making a RESTful request) then we use PUT. If we let the server decide then we use POST.
The HTTP PUT and POST methods expect an HTTP request body, so you should use a MessageBodyReader for methods that respond to PUT and POST requests.
A common application pattern is to use POST to create a resource and return a 201 response with a location header whose value is the URI to the newly created resource. In this pattern, the web service declares the URI for the newly created resource.
javax.ws.rs.HEAD: The annotated Java method maps to a HEAD request. The HEAD method is identical to GET except that the server MUST NOT return a message-body in the response. This is useful for retrieving meta-information written in response headers, without having to transport the entire content.
javax.ws.rs.OPTIONS: The annotated Java method maps to an HTTP OPTIONS request. This HTTP method returns the list of HTTP verbs that the server supports for the specified URI.
By default, the JAX-RS runtime will automatically support the methods HEAD and OPTIONS if not explicitly implemented. For HEAD, the runtime will invoke the implemented GET method, if present, and ignore the response entity, if set. For OPTIONS, the Allow response header will be set to the set of HTTP methods supported by the resource. In addition, the JAX-RS runtime will return a Web Application Definition Language (WADL) document describing the resource; see http://www.w3.org/Submission/wadl/ for more information.
