| ☰ See All Chapters |
REST Annotations
Below is the list of important JAX-RS API annotations used in REST.
@Path()
This annotation can be applied at the class level and as well as at the method level. This annotation is used to associate URI to our REST Web service. URI is the path next to the base URL.
URL : https://localhost:(port)/<ApplicationName>/<UrlPattern In Web.xml>/<path>
Here <path> is the part of URI, and this will be identified by @path annotation at class/method level.
@GET
Maps the HHTP GET request to the annotated HTTP GET method. Method annotated with @GET will respond to GET request only.
@POST
Maps the HHTP POST request to the annotated HTTP POST method. Method annotated with @POST will respond to POST request only.
@PUT
Maps the HHTP PUT request to the annotated HTTP PUT method. Method annotated with @PUT will respond to PUT request only.
@DELETE
Maps the HHTP DELETE request to the annotated HTTP DELETE method. Method annotated with @DELETE will respond to DELETE request only.
@Produces
This annotation can be applied at the class level and as well as at the method level. @Produces annotation should be used only for GET requests. This annotation specifies the MIME type of the response. The @Produces annotation has an optional element “value” value for which should be a String/String array and String should be a valid MIME type.
Example:
@Produces(value = "application/json") public String getResponse() { … … … … } @Produces("application/json") public String getResponse() { … … … … } |
While specifying MIME type we can hardcode or we can use static constants present in javax.ws.rs.core.MediaType as below. It is standard and better convention to use javax.ws.rs.core.MediaType constants instead of hardcoding.
@Produces(value=MediaType.TEXT_XML)
In case an annotation contains just a single element, it is convention to name that element value, like this: @NameOFAnnotation(value = "yes") When an annotation just contains a single element named value, you can leave out the element name, and just provide the value. Here is an example of an annotation element with only the value provided: @InsertNew("yes") |
We can configure our code to give response in only XML, or only JSON, or only HTML, or we can give response in the all the format. But service will return the response in only one format depending upon the request.
Assume, service is coded to return response in all format, then the response format depends on the content type/format that requested by the client. Usually client request the particular format in “Accept” field of header. If in header, value for “Accept” field is “application/json” the response will be in JSON format.
If service is coded to give response in only XML, then response format will be always XML. If client includes “Accept” field into header then value for “Accept” filed should be “text/xml”. Otherwise if client give some other value let’s say “application/json” to “Accept” field then since service is coded to return response only in XML, client will not get the response.
In such cases if service is giving response in any one format then it is better not to include “Accept” filed into header. The service will give response and format will be as coded.
Assume, service is coded to return response in all format, and if specific format is not requested by the client (Accept field id not added to header) the response format will be as below.
Different methods can be used to give response in different formats as below @Path("/hello") public class HelloWorldService { @GET @Produces(MediaType.APPLICATION_JSON) public String getXML() { … … }
@GET @Produces(MediaType.TEXT_XML) public String getXML() { … … } } If specific format is not requested by the client (Accept field id not added to header) the response format can be either JSON or XML which depends on server. | We can have multiple MIME types as an array for @Produces annotation. @Path("/hello") public class HelloWorldService { @Produces({ MediaType.TEXT_HTML, MediaType.APPLICATION_JSON}) public String getResponse() { … … } } By default, when invoked it returns the response in HTML as it is the first string in the array. |
@Consumes
This annotation can be applied at the class level and as well as at the method level. This annotation specifies the MIME type of the request. The @Consumes annotation has an optional element “value” value for which should be a String/String array and String should be a valid MIME type.
@Consumes(value = "application/json") public String getResponse() { … … … … } @Consumes("application/json") public String getResponse() { … … … … } |
While specifying MIME type we can hardcode or we can use static constants present in javax.ws.rs.core.MediaType as below. It is standard and better convention to use javax.ws.rs.core.MediaType constants instead of hardcoding.
@ Consumes(value = MediaType.TEXT_XML)
@Consumes annotation will decide the format that client should sent the send the data.
Consider the below code, as per the below code, client should send the data through query string and “Content-Type” filed in header should have “text/xml” value.
If "Content-Type" field is not added to header, then we will get the response. Only if added, we need to take care about the MIME type be given to "Content-Type" as that is given to @Consumes annotation.
@GET
@Produces(MediaType.TEXT_HTML)
@Consumes(MediaType.TEXT_XML)
public String getLocalCustXML(@QueryParam("s")String s) {
….
}
For the above code valid header will be
GET https://localhost:8090/06JAX_RS_ConsumeAnnotation/rest/hello?s=Manu_M
Accept-Encoding: gzip,deflate
Content-Type: application/json
Host: localhost:8090
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)
If @Consumes annotation is not used then client can send data in any MIME format.
@PathParam(), @QueryParam(), @MatrixParam(), @FormParam() annotations are studied in next chapter.
All Chapters
