Graph API versioning and the new beta version

  • Article

Folks,

We wanted to provide a few details on our API versioning strategy and our contract with application developers who consume our APIs (and client libraries).  This became a concern recently when a change on the REST API (addition of the new alternativeSignInNamesInfo collection on the User entity) lead to a break in our Azure AD Graph client library (see this Stack Overflow post).  For this particular case, the Graph team did not envisage that this change would cause a break.  However, it brought to light the importance of being very clear about our versioning contract with application developers.

API contract, versioning and breaking changes

Any breaking change to the API will result in an increment to the API version number to protect client applications. We may choose to increment the API version for non-breaking changes too (for example if we add some significantly large new capabilities).  

So, what constitutes a breaking change?

  1. Removing or Renaming APIs or API parameters
  2. Changes in behavior for an existing API
  3. Changes in Error Codes & Fault Contracts
  4. Anything that would violate the Principal of Least Astonishment

NOTE:  For Azure AD Graph API, you may notice that the addition of new JSON fields to responses does not constitute a breaking change.  For developers that generate their own client proxies (like WCF clients) our guidance is that clients should be prepared to receive properties and derived types not previously defined by the Azure AD Graph API service.  Although Azure AD Graph API is not yet OData V4 compliant (this is in our future plans), it still follows the guidance described in the Model Versioning section in the OData V4 spec.

We're also exploring the Azure Service Updates feed for promoting more visibility into Azure AD Graph API version changes.

API version lifetime

When we increment the major version of the API (for example from 1.5 to 2.0), we are signaling that all support for existing clients using previous 1.x or earlier versions will be deprecated.  We will however continue to support these previous versions for a minimum of 12 months.  Please see the Microsoft online services support policy for more details.

 Introducing version=beta

We’re also introducing a brand new version – api-version=beta.  This version of the Azure AD Graph API will provide you with an endpoint where you can try out our latest and greatest preview features, and provide the Azure AD Graph team with feedback. When our team believes that a preview feature is ready for GA, we will add that feature to the latest existing GA version (or if it constitutes a breaking change this would result in an incremented new version number).  However, we make no guarantees that a preview feature will be promoted to GA.

For the beta version, we will try to avoid any breaking changes on this version as much as possible, but we will not guarantee it.  Client applications using the beta version should expect breaking changes from time to time.  Please see preview terms of use for more information.

We will also look to produce Azure AD Graph Client Library (preview) on top of the beta Graph REST API version.  Alternatively you can use Vipr to generate your own client library if you so desire. 

 

As ever - please let us know what you think, and if anything's unclear here.