Java Reference
In-Depth Information
The
vnd
prefix stands for vendor. The
rht
string in this example represents Red Hat and, of
course, the
customers
string represents our customer database format. We end it with
+xml
to let users know that the format is XML based. We could do the same with JSON as well:
application
/
vnd
.
rht
.
customers
+
json
Now that we have a base media type name for the Red Hat format, we can append versioning
information to it so that older clients can still ask for older versions of the format:
application
/
vnd
.
rht
.
customers
+
xml
;
version
=
1.0
Here, we've kept the subtype name intact and used media type properties to specify version
information. Specifying a version property within a custom media type is a common pattern
to denote versioning information. As this customer data format evolves over time, we can
bump the version number to support newer clients without breaking older ones.
Flexible Schemas
Using media types to version your web services and applications is a great way to mitigate
and manage change as your web services and applications evolve over time. While embed-
ding version information within the media type is extremely useful, it shouldn't be the
primary way you manage change. When defining the initial and newer versions of your data
formats, you should pay special attention to backward compatibility.
Take , for instance, your initial schema should allow for extended or custom elements and at-
tributes within each and every schema type in your data format definition. Here's the initial
definition of a customer data XML schema:
<schema
<schema targetNamespace=
"http://www.example.org/customer"
xmlns=
"http://www.w3.org/2001/XMLSchema"
>
<element
<element name=
"customer"
type=
"customerType"
//>
<complexType
<complexType name=
"customerType"
>
<attribute
<attribute name=
"id"
use=
"required"
type=
"string"
//>
<anyAttribute/>
<element
<element name=
"first"
type=
"string"
minOccurs=
"1"
//>
<element
<element name=
"last"
type=
"string"
minOccurs=
"1"
//>
<any/>
</complexType>
</complexType>
</schema>
</schema>
In this example, the schema allows for adding any arbitrary attribute to the
customer
ele-
ment. It also allows documents to contain any XML element in addition to the
first
and
last
elements. If new versions of the customer XML data format retain the initial data struc-
