Versioning Policy

The Connect API is subject to version control, and as such, we need to set some ground rules around our versioning strategy. Conceptually, we believe that versioning (i.e. changes) happen on the micro level and thus our versioning strategy should align with this reality. Therefore, we will never version at the API level and will always version at a more granular level, namely at the resource level.

When to change the version?

A version number indicates a certain level of backwards-compatibility the client can expect, and as such, we will take extra care to maintain this trust. When this level of backwards-compatibility cannot be maintained, then and only then will we create a new version of a resource. The following lists which types of changes necessitate a new version and which don't:

Example changes that don't require a new version

In general, any additive change (see "must ignore policy"):

• New resource
• New HTTP methods on existing resources
• New data formats
• New attributes or elements on existing data types

Example changes that require a new version

• Structural changes for a resource’s representation (ex. one-to-one relationship changed to one-to-many relationship)
• Attributes or elements were removed for existing representations
• Removal of support for HTTP methods on existing URIs

Must ignore policy

The simplest way to maintain loose coupling between server and client is that the server and client ignore anything they don’t understand. For example, if you are parsing a response from the server whose data is represented in JSON, try not to parse and validate the document as a whole. Only search the JSON document for the data you know you need and ignore the rest. If you encounter elements or attributes which are unknown to you, don't consider it an error. The schemas provided are not meant to be used as a validation tool but only as a guide on how to construct JSON representations. This is true for the server also. If you submit an order purchase request that has extra JSON elements that the server doesn’t understand, it will ignore them and no errors will be raised.

NOTE: Be careful using frameworks such as .NET’s WCF as these types of frameworks do not play nice with this versioning policy by default, as they usually don’t support out of order elements or extension points without special care. As stated earlier, use techniques like querying the document to extract the desired information and try to avoid de-serializing it into a strongly typed class as this may cause unintended errors.

How the change will manifest itself

Since there is a one-to-one relationship between a resource and its link relation, we will version the link relation directly and the resource indirectly. As an implementation, this may translate to a version number in the URI for the resource but that will be transparent to client since you are only dependent upon link relations and not the actual URIs themselves. This will also allow us to support multiple versions of the same resource concurrently.

How long we will support older versions?

Generally, we will support older versions anywhere from 6 months up to a year depending on the circumstances. But, we will publish any deprecation warnings on an ongoing basis.