RESTful Web Services Cookbook

Chapter 13. Extensibility and Versioning

Managing change in any distributed client/server environment can be hard. In these environments, clients count on servers to honor their contracts. RESTful web services are no exception. For these web services, the contract consists of URIs, resources, the structure and content of representations, their formats, and the HTTP methods for each resource.

Any change to a server may seem benign until you consider backward compatibility. When a change is backward compatible, you need not upgrade clients at the same time as you modify the server. Clients can ignore the fact that you upgraded the server and continue to use the server as though nothing changed, barring any downtime during server upgrades.

There is another kind of compatibility called forward compatibility that may be important when you have several clients and servers upgraded at different points in time. In this case, some newer clients may be interacting with older servers. The purpose of forward compatibility is to ensure that newer clients can continue to use the older servers without disruption albeit with reduced functionality. Whether your application needs to consider backward compatibility alone or both backward and forward compatibility depends on your operating environment. The recipes described in this chapter can help you tackle both.

The characteristic that lets you maintain compatibility is extensibility. Extensibility is a design process to account for future changes. ...