Service APIs Client-Service Interactions Request and Response Management Service Implementation Service Infrastructures Service Evolution

Media Type Negotiation

Clients that use services with Resource APIs often have preferences for different media types.
How can a web service provide multiple representations of the same logical resource while minimizing the number of distinct URIs for that resource?
Web services that are used by large and diverse client populations must often accommodate different media type preferences. Some clients may, for example, prefer XML while others favor JSON. The service owner must therefore devise a means by which clients preferences can be indicated.
Approaches that encapsulate both resource identification and representation type into the URI, while common, can be tedious for service developers to implement since the format type must be parsed from the URI. These techniques also require service developers to use one distinct URI for each representation. A better approach is to leverage standard HTTP protocols for Content Negotiation.
Allow clients to indicate one or more media type preferences in HTTP request headers. Send requests to services capable of producing responses in the desired format.
Media Type Negotiation: Allow clients to indicate one or more media type preferences in HTTP request headers. Send requests to services capable of producing responses in the desired format.
The most common form of Media Type Negotiation is Server-Driven Negotiation. In this approach, the client provides its media type preferences through the Accept Request Header. The client can provide multiple preferences and can also indicate which media types are most preferred. When a request is received, the web service framework will route or select a request handler (i.e. web method) based in part on how well the client's preferences match up to the handler's Media Type Annotations.
A second style is Client-Driven Negotiation. Here again, the client sends a request containing its media type preferences through an HTTP Accept Request Header. A web service receives the request and responds by providing a list of URIs the client may consider.