Annotations for specifying request-response media types @Produces @Consumes

 

Annotations for specifying request-response media types

The Content-Type header field in HTTP describes the body's content type present in the request and response messages. The content types are represented using standard internet media types. A RESTful web service makes use of this header field to indicate the type of content in the request or response message body.

JAX-RS allows you to specify which internet media types of representation a resource can produce or consume by using the @javax.ws.rs.Produces and @javax.ws.rs.Consumes annotations, respectively. You will learn these two annotations with examples in this section.

@Produces

The @javax.ws.rs.Produces annotation is used for defining the internet media type(s) that a REST resource class method can return to the client. You can define this either at the class level (which will get defaulted for all methods) or at the method level. The method-level annotations override the class-level annotations. The possible internet media types that a REST API can produce are as follows:

• application/atom+xml
• application/json
• application/octet-stream
• application/svg+xml
• application/xhtml+xml
• application/xml
• text/html
• text/plain
• text/xml

The following example uses the @Produces annotation at the class level in order to set the default response media type as JSON for all the resource methods in this class. At runtime, the binding provider will convert the Java representation of the return value to the JSON format. This is discussed in the Understanding the data binding rules in JAX-RS section, which comes later in this chapter:

import javax.ws.rs.Path; 
import javax.ws.rs.Produces; 
import javax.ws.rs.core.MediaType; 
 
@Path("departments") 
@Produces(MediaType.APPLICATION_JSON) 
public class DepartmentService{ 
  //Class implementation goes here...     
} 

@Consumes

The @javax.ws.rs.Consumes annotation defines the internet media type(s) that the resource class methods can accept. You can define the @Consumes annotation either at the class level (which will get defaulted for all methods) or at the method level. The method-level annotations override the class-level annotations. The possible internet media types that a REST API can consume are as follows:

• application/atom+xml
• application/json
• application/octet-stream
• application/svg+xml
• application/xhtml+xml
• application/xml
• text/html
• text/plain
• text/xml
• multipart/form-data
• application/x-www-form-urlencoded

The following example illustrates how you can use the @Consumes attribute to designate a method in a class to consume a payload presented in the JSON media type. The binding provider will copy the JSON representation of an input message to the Department parameter of the createDepartment() method:

import javax.ws.rs.Consumes;  
import javax.ws.rs.core.MediaType; 
import javax.ws.rs.POST; 
 
@POST 
@Consumes(MediaType.APPLICATION_JSON) 
public void createDepartment(Department entity) { 
  //Method implementation goes here... 
}