Page Comparison

Protocol Versioning (work-in-progress proposal)

Key Points

1. The use of the a version identifier within the the URI is a useful convention in some cases but does not fully address all the issues. There are real practical reasons for following the convention, but there is extremely little value in mandating the convention or directly prescribing it's use.
2. The header approach is valid, but creation of a new header field is not required. I propose that a Link header with rel="implements" pointing to the version of the specification implemented is more than sufficient.
3. Indicating the version in use is only part of the problem. We need to clearly deal with the upgrade transition, and how to signal to the client that an upgrade is required. There are several possible approaches:## "Hard Upgrade" -- basically, reject down-level requests with an error response## "In Place Upgrade" -- attempt to handle protocol upgrade in-place and as transparently as possible## "Upgrade Redirection" -- attempt to redirect clients to new the version
4. Several mechanisms have emerged recently (Link and Prefer headers) that, when used with mechanisms that already exist within HTTP (Upgrade, 426 responses, etc) can provide a generalizable non-opensocial specific solution to what is a common, non-opensocial specific problem.

...

The ability for server and client implementions to clearly communicate which version of the OpenSocial specification a particular Service API and resource supports is critical. 

For the purpose of clearly identifying which version of the OpenSocial specification a particular application is implementing, a Web Link header referencing the base URI of the OpenSocial specification and using a rel attribute value of "implements" SHOULD be included within the HTTP request and response message.

For example, the Link would appear within the request:

GET /api/people/@me/@self HTTP/1.1
Host: example.org
Link: <http://opensocial.org/specs/3.0>; rel="implements"

And within the response:

HTTP/1.1 200 OK
Link: <http://opensocial.org/specs/3.0>; rel="implements"

A server MAY choose to implement additional conventions for identifying the current version, such as including a version indicator within the base URI of the Service API (e.g. http://example.org/v3/api/people).  Such conventions are considered out of scope.

Upgrade Indication and Transition

When a server implementation of an older version of the OpenSocial specification upgrades to a newer version, it has the responsibility to provide a clear mechanism for either continuing to support client applications using the old version or help clients migrate to the new.

Whether a server chooses to continue to support the old and new versions of the OpenSocial specification simultaneously is an implementation and business decision that is out of the scope of this specification.

However, when a server wishes to indicate to a client application that the server has been upgraded and that the old version of the API is no longer available, it SHOULD do so using an Upgrade Required response.

An "Upgrade Required Response" is an HTTP response that uses the 426 Upgrade Required status along with an "implements" Web Link.  For instance:

HTTP/1.1 426 Upgrade Required
Upgrade: OpenSocial/3.0
Connection: upgrade
Link: <http://opensocial.org/specs/3.0>; rel="implements"

Use of the 426 Upgrade Required response implies a complete cutover from one version of the specification to another.  Alternatively, a server can choose to migrate client applications incrementally, initially deploying the new version of the application side-by-side with the old.  Such a transition may or may not occur "in place", that is, requiring changes to the URI's a client uses to access the service.

For example, if a server currently exposes version 3.0 of the OpenSocial Profile Service at the URI "http://example.org/api/people", and it wishes to upgrade clients to a hypothetical version 3.1 in the future, without requiring clients to change the URIs they use to access the service, it can either continue to support the 3.0 clients transparently or perform an "in place" upgrade.

An example 3.0 client request:

GET /api/people/@me/@self HTTP/1.1
Link: <http://opensocial.org/specs/3.0>; rel="implements"

A server implementing the hypothetical 3.1 version of the OpenSocial spec can continue to respond as if it was a 3.0 implementation:

HTTP/1.1 200 OK
Link: <http://opensocial.org/specs/3.0>; rel="implements"
Content-Type: application/json

{... OpenSocial 3.0 data ...}

Or, it can perform an "in-place" upgrade:

HTTP/1.1 200 OK
Upgrade: OpenSocial/3.1
Connection: upgrade
Link: <http://opensocial.org/specs/3.1>; rel="implements"
Content-Type: application/json

{... OpenSocial 3.1 data ...}

Alternatively, the server MAY choose to deploy the new version with a new URI.

An example 3.0 client request:

GET /v3.0/api/people/@me/@self HTTP/1.1
Link: <http://opensocial.org/specs/3.0>; rel="implements"

An upgrade redirection from the server:

HTTP/1.1 301 Moved Permanently
Location: /v3.1/api/people/@me/@self HTTP/1.1
Upgrade: OpenSocial/3.1
Connection: upgrade
Link: <http://opensocial.org/specs/3.1>; rel="implements"

Client Upgrade Preferences

Implementors of client applications MAY use the Prefer HTTP Header within a request to indicate the preferred mechanism for upgrade handling.

This specification registers the following new Prefer header token values:

• return-upgrade-required: Indicates that the client prefers the server to respond with a 426 Upgrade Required response when a protocol upgrade is required by the server.
• upgrade-in-place: Indicates that the client prefers the server to attempt an in-place, transparent upgrade to a newer version of the protocol, as required.  The in-place-upgrade preference MAY include a preference value indicating the maximum allowed protocol version.  The asterisk (*) character may be used as a wildcard. For instance, "Prefer: upgrade-in-place=3." indicates that the client prefers an in-place-upgrade for any protocol version matching the pattern "3.*" (e.g. 3.1, 3.2, 3.3, etc).
• upgrade-redirect: Indicates that the client prefers the server to use redirects when upgrading protocols.  If a redirect is not available, then the 426 Upgrade Required response is preferred.

These Preference tokens MAY be used together.

For example, a client can indicate to the server that it is capable of handling automatic in-place upgrade for any 3.* version of the specification but prefers use of the 426 Upgrade Required response for all other cases:

GET /api/people/@me/@self HTTP/1.1
Link: <http://opensocial.org/specs/3.1>; rel="implements"
Prefer: return-upgrade-required, upgrade-in-place=3.*

Or, for instance, a client can indicate that is is capable of handling automatic in-place upgrades for any 3.* version and prefers use of redirects for all other cases:

GET /api/people/@me/@self HTTP/1.1
Link: <http://opensocial.org/specs/3.1>; rel="implements"
Prefer: upgrade-redirect, upgrade-in-place=3.*

...