API compatibility policy and deprecation policies

Compatibility policy

Compatible with earlier versions or non-breaking changes

Adding a resource URI that might extend an existing API resource

This change is generally safe. However, the change must consider popular client frameworks that might generate code that conflicts with this change. The following examples are types of changes to avoid that might break client-generated code.

• An API exists /v1.0/foo/bar. The code generator might generate GetBar as a client method. If a new API is introduced /v1.0/foo/{param}, where {param} is an arbitrary string, the code generator might generate the new client method as GetFoo(String param). This change can cause a breaking change on the client because the logic that was embedded in GetBar is no longer invoked.
• A current path /v1.0/foo/bar might result in client-generated code GetBar and GetBarAsync. The addition of an API /v1.0/foo/Async conflicts with this generated code.

Adding an HTTP method to an API interface

This change is safe on the condition that the request payload before this change continues to exist and behaves in the same manner. An optional field or fields can be added to an existing API's request body or as a query string parameter.

Adding optional request headers

This change is safe on the condition that the request before this change continues to respond in the same manner.

Adding an allowed value to an existing property

API models use strings to represent properties that allow a constrained list of values. For example, type in a resource can be documented to list out the current list of resource types. The client is expected to use a generic string for these types instead of using strict deserialization of a well-defined enum type. A resource that accepts a property with multiple possible values can be enhanced to allow more values. This new value or values can introduce corresponding new properties and validation rules. A client must ensure that it does not validate on non-existent enum values by, for example, making a request with an invalid enum value and expecting an error response.

Existing property values continue to support existing behavior. Any client code that contains, for example, branching logic on the resource type, continues to function as before.

Adding optional fields or headers or both to a response

Optional fields and headers can be added to an API response at any time. The client must adjust for such changes.

Changing an error message and resource descriptions in the API response

The messageId field in an error response is considered unchangeable and is expected to always cover the stated list of error conditions or cases. The description that is associated with this message can change, without changing the semantic meaning of the message to a user.

Clients must not build logic based on the messageDescription attribute.

Increasing the scope of an error message ID

The messageId field refers to one or more error conditions. This messageId can be extended to cover more error conditions at any time. However, any such extension is expected to be logical and not arbitrary. The new error conditions must closely relate to an existing error condition that is covered by this message.

Rate-limit headers and errors

The rate limits can be adjusted on API endpoints during the lifetime of the API and does not require a version update.

The clients that receive the HTTP status code 429 for too many requests must make adjustments.

Breaking changes

Removing or renaming an API resource endpoint or HTTP method

This type of change breaks any client that uses the API and is not allowed, unless a strong security need to make this change exists. Every effort is made to avoid such a change.

Removing or renaming enum values

Values for enum can be added but not removed.

Changing the type of a field

In general, the type of a field must not change. However, if the API implementation is able to accept the previous type and respond with the previous type, this change is considered compatible with earlier versions.

Changing visible behavior of existing requests

If a request previously resulted in certain action or response, it must continue to behave in this manner. The only exception is the extensions that are allowed to an existing contract in the form of new error messages, HTTP status codes, and request or response fields.

Deprecation policy