This recipe discusses how to make compatible changes to XML and JSON representations. See Recipe 13.3 to learn about extending Atom representations.
You want to know how to keep changes to XML/JSON representations compatible with existing clients.
Design an XML format to keep the child elements unordered. When making changes to XML and JSON, preserve the hierarchical structure so that clients can continue to follow the same structure to extract data.
Make new data elements in requests optional to maintain compatibility with existing clients. Clients that do not send new data fields must be able to continue to function.
Do not remove or rename any data fields from representations in response bodies.
Although headers are part of a representation, as long as clients and servers use headers correctly as per HTTP, headers should not affect compatibility. Most compatibility problems occur with the body of representations.
Using extensible formats such as XML and JSON is necessary to allow servers to make changes. However, using such extensible formats does not automatically guarantee that the representations are compatible. To keep clients from breaking, you need to preserve the way clients read data from the body of a representation. The following example illustrates a compatible change:
# Response before change HTTP/1.1 200 OK Content-Type: application/xml;charset=UTF-8 <user> <first-name>John</first-name> ...