1.7 Versioning and Capability Negotiation

This document covers versioning issues in the following areas: <1>

Supported Transports: This document can be implemented on top of the Atom Publishing Protocol (AtomPub) described in Transport (section 2.1).

Protocol Versions: Clients specify the protocol version by using the DataServiceVersion (section 2.2.5.3) and MaxDataServiceVersion (section 2.2.5.7) request headers. Servers specify the protocol version by using the DataServiceVersion (section 2.2.5.3) response header.

Security and Authentication Methods: This document supports (but does not require) any authentication scheme that can be supported by using HTTP request and response headers. An example of such an authentication protocol is HTTP Basic Access Authentication described in [RFC2617].

Localization: This document does not specify any localization-dependent behavior.

Capability Negotiation: The OData protocol that is defined in this document enables limited capability negotiation using the DataServiceVersion (section 2.2.5.3) and MaxDataServiceVersion (section 2.2.5.7) version request headers and the DataServiceVersion (section 2.2.5.3) response header. These headers provide a way to version the OData protocol and do not act as a versioning scheme for the AtomPub in general.

On a request from the client to data service, the DataServiceVersion (section 2.2.5.3) and MaxDataServiceVersion (section 2.2.5.7) version headers may be specified.

If present on the request, the DataServiceVersion (section 2.2.5.3) header value states the version of the protocol used by the client to generate the request. If no DataServiceVersion (section 2.2.5.3) header is provided, then the server must assume a value equal to the maximum version number the server supports.

If present on the request, the MaxDataServiceVersion (section 2.2.5.7) header value specifies the maximum version number the client can accept in a response. The client should set this value to the maximum version number of the protocol it is able to interpret. If the header is not present in a request, the server must assume the same version number as that specified by the DataServiceVersion (section 2.2.5.3) header. If a DataServiceVersion (section 2.2.5.3) header is not present, then the server should assume the client can interpret the maximum version number the server can interpret.

When the server receives a request, it must validate that the version number specified in the DataServiceVersion (section 2.2.5.3) header (or derived value if the header is not present) is less than or equal to the maximum version number it supports. If it is not, then the server must return a response with a 4xx response code. The server should also return a description of the error using the error format defined in Error Response (section 2.2.8.1).

In addition, a server must validate that the version number specified in the MaxDataServiceVersion (section 2.2.5.7) header (or derived value if the header is not present) is greater than or equal to the minimum version number the server needs to use to generate the response. If it is not, then the server must return an error response, described in Error Response (section 2.2.8.1).

On a response from the server to the client, the DataServiceVersion (section 2.2.5.3) header should be specified. The value states the version of the protocol the server used to generate the request and that should be used by the client to determine if it can correctly interpret the response (that is, the value is not larger than the value of the MaxDataServiceVersion (section 2.2.5.7) header sent in the associated request). The value of the header should be the lowest version of the protocol the server can use to fulfill the request.