RESTful之Content negotiation

Content negotiation

Content negotiation

Content negotiation means allowing different representations of a resource in the
same URI so that clients can make a choice on what suits them best.

"HTTP has provisions for several mechanisms for "content negotiation" - the
process of selecting the best representation for a given response when there are
multiple representations available."
– RFC 2616, Fielding et al.

There are different patterns for content negotiation.

 These are as follows:
• Using HTTP headers
• Using URL patterns

Content negotiation using HTTP headers

When the client sends requests to create or update a resource, there is some form
of payload that should be transferred from the client to the endpoint. Also, when
a response is generated, a payload can be sent back to the client. These payloads
are handled by HTTP request and response entities, which are sent as part of the
HTTP messages body.
Entities are sent via a request, usually for HTTP POST and PUT methods, or they
are returned in a response for the HTTP methods. The Content-Type HTTP header
is used to indicate the MIME type of the entity being sent by the server. Common
examples of content types are "text/plain", "application/xml", "text/html",
"application/json", "image/gif", and "image/jpeg".
A client can make a request to the server and specify what media types it can
handle and what is its order of preference as part of the "Accept" HTTP header.
The client can also specify in what language it wants the response as part of the
"Accept-Language" header to be. If no Accept header is present in the request,
the server can send the representation it chooses.
The JAX-RS specification provides standard annotations to support content
negotiation. These are javax.ws.rs.Produces and javax.ws.rs.Consumes
annotations. The following snippet shows an example of the @Produces
annotation in a resource method:

@GET
@Path("orders")
@Produces(MediaType.APPLICATION_JSON)
public List<Coffee> getCoffeeList(){
return CoffeeService.getCoffeeList();
}

The getCoffeeList() method returns a list of coffees and is annotated with
@Produces(MediaType.APPLICATION_JSON). The @Produces annotation is used
to specify which MIME types the resource can send back to the client and match
it up to the client's Accept header.

This method will produce a response as shown:

X-Powered-By: Servlet/3.1 JSP/2.3 (GlassFish Server Open Source
Edition 4.0 Java/Oracle Corporation/1.7)
Server: GlassFish Server Open Source Edition 4.0
Content-Type: application/json
Date: Thu, 31 Jul 2014 15:25:17 GMT
Content-Length: 268
{
"coffees": [
{
"Id": 10,
"Name": "Cappuchino",
"Price": 3.82,
"Type": "Iced",
"Size": "Medium"
},
{
"Id": 11,
"Name": "Americano",
"Price": 3.42,
"Type": "Brewed",
"Size": "Large"
}
]
}

In a resource, if no methods are able to produce the MIME type requested by a client
request, the JAX-RS runtime sends back an HTTP 406 Not Acceptable error.
The following snippet shows a resource method annotated with the
@Consumes annotation:

@POST
@Consumes(MediaType.APPLICATION_JSON)
@Produces(MediaType.APPLICATION_JSON)
public Response addCoffee(Coffee coffee) {
// Implementation here
}

The @Consumes annotation specifies which media types the resource can consume.
When a client makes a request, JAX-RS finds all the methods that will match the path,
and it will then invoke the method based on the content type sent by the client.
If a resource is unable to consume the MIME type of a client request, the JAX-RS
runtime sends back an HTTP 415 ("Unsupported Media Type") error.

Multiple MIME types can be specified in the @Produces or @Consumes annotation
as @Produces(MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML).
Along with the support for static content negotiation, JAX-RS also contains runtime
content negotiation support using the javax.ws.rs.core.Variant class and the
javax.ws.rs.core.Request objects. A Variant object in a JAX-RS specification
is a combination of media types, content-language, and content encoding as well
as ETags, last-modified headers, and other preconditions. The Variant object
defines the resource representation that is supported by the server. The Variant.
VariantListBuilder class is used to build a list of representation variants.
The following code snippet shows how to create a list of resource representation
variants:

List<Variant> variants = Variant.mediatypes("application/xml",
"application/json").build();

The code snippet calls the build method of the VariantListBuilder class.
The Request.selectVariant method takes a list of Variant objects and chooses
the one based on the client's Accept header, as shown in the following snippet:

@GET
public Response getCoffee(@Context Request r) {
List<Variant> vs = ...;
Variant v = r.selectVariant(vs);
if (v == null) {
return Response.notAcceptable(vs).build();
} else {
Coffee coffee = ..//select the representation based on v
return Response.ok(coffee, v);
}
}

Content negotiation based on URL patterns

Another approach for content negotiation adopted by some APIs is to send the
resource representation based on the extension of a resource in the URL. For
example, a client can ask for details using http://foo.api.com/v2/library/
books.xml or http://foo.api.com/v2/library/books.json. The server has
different methods, which can handle the two URIs. However, both of these are
representations of the same resource.

	@Path("/v1/books/")
	public class BookResource {

	@Path("{resourceID}.xml")
	@GET
	public Response getBookInXML(@PathParam("resourceID") String
	resourceID) {
	//Return Response with entity in XML
	}
	@Path("{resourceID}.json")
	@GET
	public Response getBookInJSON(@PathParam("resourceID") String
	resourceID) {
	//Return Response with entity in JSON
	}
	}

As you can see in the preceding snippet, there are two methods defined:
getBookInXML() and getBookInJSON(), and the response is returned based
on the path of the URL.

It is a good practice to use the HTTP content negotiation Accept
header. Using headers for content negotiation provides a clear
separation of IT concerns from business. The other advantage with
using the Accept header for content negotiation is that there is
only one resource method for all the different representations.

读书笔记：RESTful Java Patterns and Best Practices