2.14 Resource Versioning

SData provides a URL syntax to refer to a specific “version” of a resource. This syntax is most often used in schema URLs. For example:

http://www.example.com/sdata/myApp/myContract/-/$schema?version=1.0.7

This URL returns a specific version of the schema, while a URL without a version returns the current version of the schema.

As a general rule, versioned resources MUST have two important properties:

The versions SHOULD have a reasonable life time. Previous versions should be kept when the resource is modified. This should not be too strict though and SData does not require that versions be kept forever, they may be purged from time to time.
Versions MUST be unchangeable. If the consumer requests the same version twice, he should get the same response.

As versions are unchangeable, the provider MUST set the Expires HTTP header to the end of the expected lifetime of the version when serving GET requests that include a version parameter. For example a GET on the example URL would return a response:

200 OK
Content-Type: application/xml
Expires: Thu, 06 Aug 2009 16:00:00 GMT

<xs:schema xmlns:tns="http://schemas.sage.com/myContract" 
           targetNamespace="http://schemas.sage.com/myContract" 
           xmlns:sme="http://schemas.sage.com/sdata/sme/2007" 
           xmlns:xs="http://www.w3.org/2001/XMLSchema">
...

The HTTP recommendation is to set the date to one year in the future to indicate an infinite lifespan

Versioning is encouraged on schema resources because it allows consumers to cache schemas efficiently. It also enables providers to ensure consistency between data and metadata. When the feed and its schema are retrieved separately, there is always a risk of mismatch. This risk goes away if the schema URL includes a version parameter.

The version parameter MAY also be applied to application resources but this feature requires that the application keep history trails (payroll applications often do this). The application MUST guarantee that versioned resources have a reasonable lifetime and that their versions are unchangeable.

SData providers MAY support resource versioning. If they do, they MUST use the version parameter and follow the above rules