Best Practice: Use a Profile to Request Plain Old XML

State: DRAFT

Contact: Ian Green

Scope

This Best Practice is intended to make it easier for developers to consume XML REST services provided by IBM and third-party products.

Background

XML is used to serialize many types of resource. Some of the XML serializations are very difficult to process using standard XML technologies such as XPath. For example, RDF can be serialized as RDF/XML in many different but equivalent ways, which makes it unsuited to processing using XPath. XML serializations that can be processed using XPath and other standard XML processing technologies are referred to as Plain Old XML or POX.

An XML REST service is a REST API that provides XML representations of resources. Rational Team Concert (RTC), Rational Quality Manager (RQM), and many other products provide XML REST services. In some cases, an XML REST service may provide both RDF/XML and POX representations, in which case the service must provide a mechanism for consumers to request their preferred representations. The service may provide different URIs for the different representations, or it may determine the preferred representation from the HTTP Accept header.

Some consumers may only be able to process one type of XML. For example, an RDF indexing application may be able to process just RDF/XML, while a document generation application, such as Rational Publishing Engine (RPE), may be able to process just POX.

Problem Statement

Some products have taken the approach of providing different URIs for different representations of the same resource. For example, many Rational products provide one set of URIs for POX and another for RDF/XML. This approach causes a problem for RPE because the POX representations sometimes contain links to the RDF/XML representation URIs. The relation between a POX URI and the corresponding RDF/XML URI is complex. Computing the POX URI from an RDF/XML URI is fragile and error-prone.

The existence of two or more URIs for a given resource is referred to as aliasing and is considered to be a bad practice. Rational is therefore planning to unify the APIs by making each URI respond to requests for all formats. This means that if a request for RDF/XML to sent to a POX URI then the request will be redirected to the RDF/XML URI.

The assigned media type for XML is application/xml. The assigned media type for RDF/XML is application/rdf+xml. Unfortunately, the RDF/XML URIs may return RDF/XML even when application/xml is requested. We therefore need a mechanism for requesting POX from RDF/XML URIs.

Recommendation

This Best Practice defines a URI to identify a profile for POX and describes how it should be used to request a POX representation of a resource.

As mentioned above, some RDF/XML URIs may return RDF/XML when application/xml is requested. One solution is to reserve the media type text/xml for POX. Unfortunately, RFC 7303 XML Media Types makes application/xml and text/xml equivalent.

Another potential solution is to add a media type parameter to the Accept header. However, no appropriate media type parameters are defined for XML and clients must ignore unknown media type parameters.

This leads us to the HTTP Link header and the 'profile' link relation as defined in RFC 6906, The 'profile' Link Relation Type.

A profile is a set of additional semantics and processing rules that build on a media type. In the present case, we view POX as a profile for XML documents that can be processed using standard XML processing technologies, especially XPath. The structure of the POX document may be described using an XML Schema.

A profile is identified by a URI. We use the following URI for the POX profile:

http://jazz.net/ns/profile#POX

This URI is part of the http://http://jazz.net/ns/profile# namespace which has been created for profile URIs. Additional profile URIs will be added as required.

This URI is used in the HTTP Link header along with Accept as follows:

Accept: application/xml
Link: <http://jazz.net/ns/profile#POX>; rel="profile"

When these headers are present in an HTTP GET request then the service MUST either return a POX representation if available or fail the request with a 406 Not acceptable response.

The following table summarizes the expected behavior of unified RDF/XML and POX REST services. Each row describes an HTTP GET request. The first column gives the headers. The second column gives the behavior of the RDF/XML URIs. The third column gives the behavior of the POX URIs.

When the request is delegated, the service should return the representation in the response and include the delegated URI in the Content-Location HTTP header. NEW The service MUST include the Link: <http://jazz.net/ns/profile#POX>; rel="profile" in the response so that the client can determine that the request was delegated. A service which is unable or unwilling to honour the Link: <http://jazz.net/ns/profile#POX>; rel="profile" request, MUST NOT include this header in any response. END

Note that if application/xml is specified without the Link header, then care must be taken to preserve the current behavior and avoid breaking existing clients.

Impact to Products

XML REST API providers, such as RQM, must unify their RDF/XML and POX APIs by implementing the behavior described in the preceding table.

POX-only consumers, such as RPE, must include the Link header with the POX profile in HTTP GET requests.

See Also

• RFC 6906, The 'profile' Link Relation Type
• RFC 7303, XML Media Types
• Plain Old XML