Versioning Protocol of Astoria

Now that CTP1 of Astoria has been made public, we have two different versions of server and client that can interact with each other. How does Astoria handle the versioning for the various possible interactions? While this question probably does not concern normal users who sticks to our client library, it is something worth to know especially when you run into a bad request that tells you “your version is not supported”.

If you have ever looked at the headers of the HTTP request and response between the client and the server in V1, you’d likely noticed two headers in there: DataServiceVersion and MaxDataServiceVersion. These two headers are the magical tags that controls what request we would accept and what request we would fail. In short, DataServiceVersion defines the protocol version of the particular request/response it is associated with, and MaxDataServiceVersion is a request-only header that tells the server the maximum protocol version of the response the client is willing to accept.

So take our V1 client for example. It can only understand Data Service protocol version “1.0”, so for all the requests, it will put:

DataServiceVersion: 1.0;
MaxDataServiceVersion: 1.0;

Any Astoria service will be able to look at these headers and comply to the specified protocol. For example, in this case a request to “/Customers/$count” would fail, because the “$count” segment does not exist in protocol version 1.0. Another example is “Friendly Feeds”, when turned on, it will require that the client can at least understand protocol version “2.0” regardless of the request’s version (since the format of the feed changes and thus will break the V1 client). In this case the request will also fail, but because of the MaxDataServiceVersion is set to 1.0.

The idea behind defining a protocol version for each request is to eliminate possible ambiguous situations if one ever pops up in the future. For example, let’s say the behavior of “$count” end point is changed in Astoria V5. In this situation, to avoid breaking every lower version clients, the service will rely on the DataServiceVersion header to figure out what is the actual meaning when it sees a request to “$count”.

Not every client choose to set these headers. IE for example, can browse our services and it doesn’t understand a thing about Astoria protocol. So when the one of the headers is not present, Astoria’s implementation will set it to the newest version it can understand.

Going back from the service to the client is easier. The server will only write the header “DataServiceVersion”, which tells the client the protocol associated with the particular response. Of course, the server will only do so if the response version number is less than or equal to the MaxDataServiceVersion of the request. So in theory the response is “version-proof” in a sense that the client should at least be able to understand the result. However, this information becomes useful in the ambiguous situation mentioned above, where the client should actively check the response version and figure out the correct meaning for it.

update: the following is not longer true. We now use protocol version "2.0" for all new features. See Versioning Protocol of Astoria Part II for details.

One side note on the current protocol version used in V1.5 CTP1: you’ll notice that all versioning headers is either 1.0 or 2.0, but our product version is “1.5”. This mismatch could be confusing to many people and was unintentional. In the final release of V1.5, all version 2.0 headers will be changed to “1.5” instead.