Java Reference
In-Depth Information
@GET
@Produces
(
"application/xml"
)
public
public
Customer
getXml
() {...}
@GET
@Produces
(
"application/json"
)
public
public
Customer
getJson
() {...}
}
For this
CustomerService
JAX-RS resource class, if a request of
GET /customers.json
came in, the JAX-RS implementation would extract the
.json
suffix and remove it from the
request path. It would then look in its media type mappings for a media type that matched
json
. In this case, let's say
json
mapped to
application/json
. It would use this informa-
tion instead of the
Accept
header and dispatch this request to the
getJson()
method.
Leveraging Content Negotiation
Most of the examples so far in this chapter have used conneg simply to differentiate between
well-known media types like XML and JSON. While this is very useful to help service dif-
ferent types of clients, it's not the main purpose of conneg. Your web services will evolve
over time. New features will be added. Expanded datasets will be offered. Data formats will
change and evolve. How do you manage these changes? How can you manage older clients
that can only work with older versions of your services? Modeling your application design
around conneg can address a lot of these issues. Let's discuss some of the design decisions
you must make to leverage conneg when designing and building your applications.
Creating New Media Types
An important principle of REST is that the complexities of your resources are encapsulated
within the data formats you are exchanging. While location information (URIs) and protocol
methods remain fixed, data formats can evolve. This is a very important thing to remember
and consider when you are planning how your web services are going to handle versioning.
Since complexity is confined to your data formats, clients can use media types to ask for dif-
ferent format versions. A common way to address this is to design your applications to
define their own new media types. The convention is to combine a
vnd
prefix, the name of
your new format, and a concrete media type suffix delimited by the “+” character. For ex-
ample, let's say the company Red Hat had a specific XML format for its customer database.
The media type name might look like this:
application
/
vnd
.
rht
.
customers
+
xml
