Share via

1.7 Versioning and Capability Negotiation

  • Article

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.

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

If present in 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, the server assumes a value equal to the maximum version number the server supports.

If present in 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 sets 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 assumes 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, the server assumes the client can interpret the maximum version number the server can interpret.

When the server receives a request, it validates 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, the server returns a response with a 4xx response code. The server also returns a description of the error by using the error format defined in Error Response (section 2.2.8.1).

In addition, a server validates 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, the server returns an error response, described in Error Response (section 2.2.8.1).

In a response from the server to the client, the DataServiceVersion (section 2.2.5.3) header is specified. The value states the version of the protocol that the server used in the request to generate the response and that is 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 headeris the lowest version of the protocol the server can use to fulfill the request.