| |
Problem
Service consumers can have diverse requirements, especially when they exist as alternative programs in mobile devices or on desktop applications. Whereas most consumers will tend to expect a standard XML representation, others may require different formats, such as binary-encoded images or portable data format (PDF) based data.
Solution
Services are designed to support data exchange in multiple or alternative data formats. Either service contracts are extended to include additional capabilities with the functionality to receive and respond with messages containing different formats, or processing is added to transform a serviceˇ¦s natural data representation format to and from the consumerˇ¦s desired representation format.
Application
There are two common approaches for supporting Alternative Format in services:
|
•
|
Use an attachment technology to associate the alternatively formatted data with an XML message and configure the service to address the processing of these attached content formats.
|
|
•
|
Use any one of the supported content-types or custom representation, available natively to the application protocol (such as HTTP) and configure the service to address the processing of these different content formats.
|
For SOAP-based Web services, this pattern can be applied using a SOAP-based attachment technology, such as SwA (SOAP with Attachments), which allows non-XML-based data to be associated with a SOAP message. SwA can be further supplemented by XML-binary Optimization Packaging (XOP), SOAP Message Transmission Optimization Mechanism (MTOM), and Resource Representation SOAP Header Block (RRSHB).
All of these technologies work together with Multipurpose Internet Mail Extension (MIME) packaging standards to represent and encode data in different formats.
For example, a SOAP message may contain the following header that establishes the primary message contents as being XML:
MIME-Version: 1.0
Content-Type: Multipart/Related; boundary=PART_BOUNDARY;
type="application/xop+xml";
start="";
startinfo="application/soap+xml"
...along with a separate part that identifies the attached content as being a PNG image file:
Content-Type: image/png
Content-Transfer-Encoding: binary
Content-ID: <image@alleywoodcorp.com>
|
Note: An alternative technology to SwA is WS-Attachments, which is based on Direct Internet Message Encapsulation (DIME), an alternative media representation standard to MIME.
|
Another approach (to the latter option) is to leverage HTTP specifications, to accommodate the need for alternative formats of information. This mechanism of interaction between service and its consumer to decide on the best content format (within the context of HTTP) is termed content negotiation. HTTP Specification provides the Accept request header, Content-Type request and response headers along with Accept-Language, Accept-Range and other Accept headers to accomplish this feature.
The Content-Type and Accept headers specify any one of the valid media types from the Internet Media Types listing. As new formats become prominent, they also get added to the standards list and can be used. The media types are of the general format-
media-type = type "/" subtype *( ";" parameter )
For example, to represent XML the media-type value would be text/xml or application/xml, to represent HTML it is text/html, and the Adobe PDF format is application/pdf.
When using HTTP functionality with a REST framework (such as Restlet etc.) of choice, the JSON (JavaScript Object Notation) format is also commonly supported. Hence a web application consuming this service from a browser can process this response with little overhead as these are just another JavaScript objects.
For example, this simple XML fragment:
<customers>
<customer>
<name>John Smith</name>
<type>Gold</type>
</customer>
</customers>
...would be represented in JSON as follows:
{
customers:{
customer:[
{
name:"John Smith",
type:"Gold"
}
]
}
}
Impact
The primary impact is on the service implementation, since the additional logic to accept the various media-types and respond with unique media-types has to be addressed as part of the implementation. The impact on the consumer is that they have to perform additional calls to the service to inquire about the supported content as part of the content negotiation process.
Case Study Example
Alleywood has been providing the Customer Listing service to all of its internal consumers. However, new requirements have recently emerged by some new consumer program design projects that need data returned to them in a JSON representation.
This requirement is related to the fact that these new programs must provide a user-interface with a dynamic query feature. Therefore, the customer data is ideally delivered in the JSON representation format.
The development team proposes two data structures to address these requirements:
|
•
|
the listing of customers given the first two letters of the name (last name in case of people and entity name in case of businesses)
|
|
•
|
customer details for a given customer
|
Additionally, this rich user-interface needs to be able to handle queries specifically on the last name of customers. To address this function, the development team decides to enhance the service implementation itself. They propose to accept a specific query string in the URL to provide the listing of customers meeting the query criteria.
As a result, the /services/customers URI structure is enhanced to accept parameters, as follows:
/services/customers/?q=nameStr
The reason this approach is chosen over the option of modifying the underlying service implementation to return a listing based on /services/customers/[id] is to keep the distinction between the "official" customer REST service (as represented by the URL /services/customers/[id]) and the temporary collection of customer data based on a query that could change dynamically.
A sample JSON data structure that might be provided by the updated Customer service is shown here:
{"customer": {
"id": "ab123", "type": "gold",
"profile": {
"name": "Ablutions Solutions",
"owner": "Charlie Jones",
"contact": "Bonita Watson",
"address": {
"street": "10 Dowing St.",
"city": "Charleston",
"state": "SC",
"zip": "99999"
}
"phone": "1-222-444-5555",
"sector": "Public Construction"
},
"accounts": {
"customer_id": "ab123",
"account": [
{ "id": "19829", "limit": 20000, "type": "Business
Checking","since": "Jan 20, 2001"},
{"id": "12998","limit": 3000, "type": "Savings",
"since": "Jan 20, 2001"}
]
}
}}
If the consumer wants to query for a particular substring of the customer name, the customer collection data structure for query "an" string (by using http://alleywoodcorp.com/services/customers/?q=an yields the following:
{"customers": {
"q": "an",
"customer": [
{"name": "Anderson Solutions", "id":"an123"},
{"name": "Anthony, Mark", "id":"mams12"},
{"name": "Anthony Brothers", "id":"an909"}
]
}}
|
