How do an OData client and service agree on a protocol version, and how did v2's DataServiceVersion headers differ from v4's OData-Version and OData-MaxVersion?

## What is being negotiated An OData **protocol version** governs three things at once: URL conventions, payload format and HTTP interaction rules. It is not the version of your data model or of your API. Both OData lines let the two sides state two facts on every exchange: - the version used to **produce a payload** (request or response), and - the **maximum version** the client can **read** in a response. The headers and the selection rule changed between the Microsoft-published v2 and the OASIS v4 line. | Aspect | OData v2 | OData 4.0 / 4.01 | |---|---|---| | Version of a payload | `DataServiceVersion` | `OData-Version` | | Client's ceiling | `MaxDataServiceVersion` | `OData-MaxVersion` | | Response version chosen | the **lowest** version that can fulfil the request (SHOULD) | the **greatest** supported version not above `OData-MaxVersion` (MUST) | | Response header | should be sent | MUST be sent | | Version values | `1.0`, `2.0` | `4.0`, `4.01` | ## The v2 rules The v2 overview calls this "limited capability negotiation" and only *highly encourages* the headers. 1. If a request has no `DataServiceVersion`, the server must assume the highest version it supports. 2. If it has no `MaxDataServiceVersion`, the server assumes the same value as `DataServiceVersion`; if both are missing, it assumes the client can read the server's maximum. 3. If the request's `DataServiceVersion` exceeds what the server supports, the server must answer with a 4xx and should describe the error in the OData error format. 4. If `MaxDataServiceVersion` is below the minimum version needed to build the response, the server must return an error. 5. The response `DataServiceVersion` should be the **lowest** version that fulfils the request. Rule 5 means a plain read is often answered as `1.0`, while a request using a 2.0-only feature such as `$inlinecount` or `$select` comes back as `2.0`. A v2 client therefore has to cope with both response shapes. ## The v4 rules - A client **SHOULD** send `OData-Version` to state the version of its request payload. The service **MUST** interpret the payload by that version or fail with a 4xx. - Without `OData-Version`, the service **MUST** assume the minimum of `OData-MaxVersion` (if sent) and the highest version it understands. - A client **SHOULD** send `OData-MaxVersion`; the 4.01 interoperability list goes further and says clients **MUST**. If it is sent, the service **MUST** generate the response at the **greatest supported version** at or below it, using decimal comparison. - The service **MUST** put `OData-Version` on every response, and the client **MUST** read the payload by that version. - Request and response payloads are independent and may carry different `OData-Version` values. ```http GET /sales/Orders?$top=1 HTTP/1.1 Host: api.example.com OData-MaxVersion: 4.0 Accept: application/json HTTP/1.1 200 OK OData-Version: 4.0 Vary: OData-MaxVersion Content-Type: application/json {"@odata.context": "https://api.example.com/sales/$metadata#Orders", "value": [ ... ]} ``` Here a service that supports both 4.0 and 4.01 answers in 4.0 because the client capped it there, so the payload keeps the `odata.` prefix. ## When the client sends no ceiling This rule moved between the OASIS releases: - **4.0**: the service SHOULD treat the request as if `OData-MaxVersion` were its own maximum. - **4.01**: the service SHOULD return responses with the same version over time, treating the missing header as the maximum version it supported **at its initial publication**. A service launched on 4.0 and later upgraded therefore keeps answering silent clients in 4.0. The 4.01 conformance list still allows a service to return 4.01 content to a client that did not send `OData-MaxVersion: 4.0`, so the safe client habit is to always send the header. ## Caching and batches - If a response varies with the version chosen, 4.01 requires the service to send `Vary` listing `OData-MaxVersion`, so a shared cache does not hand a 4.01 body to a 4.0 client. - Inside a batch, a part without its own version headers inherits those of the enclosing batch request. ## What the headers do not do They version the **protocol**, not your entity model. Breaking model changes are a separate mechanism: 4.0 expects a new service root, and 4.01 adds schema versioning with the `Core.SchemaVersion` annotation and the `$schemaversion` query option. A v4 specification also defines no handling for `DataServiceVersion`, so these headers cannot bridge a v2 client to a v4 service.