×

Public REST API Compatibility and Deprecation Policy

Author: Ryan Haber
Categories: []
Tags: [‘developer’]


Compatibility

Backward compatibility

Wherever possible, we will maintain backward compatibility for REST resources and their representations.

An API is backward compatible if a program written using one version of the API will continue to work the same way without modification when using future versions of the API.

If we need to change a representation so that it is not backward compatible, we will create a new resource or media type using the new representation. In such cases, we will maintain the old resource or media type according to the deprecation policy described below. Such a change to a representation of a resource constitutes a version increment to the corresponding REST API(s). We may change the behavior of an API without warning if the existing behavior is incorrect or creates a security vulnerability.

Stable URIs

If a resource exists at a particular URI, that same resource will continue to exist with the same meaning in future versions.

HTTP Response Codes

Parameters and Data

Canonical URIs

Stable representations

If we document a resource as available in a specific media type, e.g., using the Content-Type header, we will keep it available using that media type. If a resource returns a default media type in the absence of content negotiation, we will maintain that default.

Structured representations (application/json)

We further commit to the stability of resources with a media type of application/json.

Values Not Included in Compatibility Policy

The following are not covered by this compatibility policy:

The above items are not part of the API. They may change without warning. It is your responsibility to adhere to limits and behaviors as described in the API documentation or the developer community.

Structured representations of paged data and sorting behavior in API responses follow the policies described in the “Structured Representation” section of this document.

API versioning

Version Increments

Our APIs do not tag responses with their version number. The version is part of the URL used to call the API. We increment version numbers only for REST API endpoints affected by a particular change. The “expected” or “preferred” version of an API end-point is always the highest version of the endpoint. The existence of a higher-versioned endpoint implies that we have deprecated some aspect of the previous version of the endpoint or associated resource. Once a newer version of an API endpoint becomes available, we will mark any prior versions of the endpoint as deprecated. If we deprecate an API version, we will follow the policy laid out below.

Forward compatibility

We make no guarantee of forward compatibility in our REST APIs. These non- binding guidelines about our approach to forward-compatibility may help you plan your projects.

An API is forward-compatible if a program written using one version of the API will also work the same way without modification when using previous versions of the API.

Where appropriate, we follow the Robustness Principle. This means that in some cases, an API determines how to handle a request based only on the parts that it recognizes. There are some notable exceptions.

Deprecation

Deprecation Policy

This REST API deprecation policy is to be understood in conjunction with any other relevant deprecation policies. When there is a conflict of policy, the most restrictive policy applies.

Announcements

We make every effort to notify consumers about new deprecations through all relevant channels. This includes:

Time frames

We will give developers the longest possible notice of deprecations to publicly accessible REST APIs. We maintain deprecated REST APIs in their original forms for at least 1 year. Deprecations take effect with the Blackboard Learn semi-annual releases for self-hosted and managed-hosting customers. Exceptions to this policy apply in case of critical security vulnerabilities or functional defects.

Detectability

Requests made to deprecated APIs return a header with the response to notify the consumer that the endpoint is deprecated. We use the warning header Warning: 299 - ‘Deprecated API; @since version’. For more information, see https://tools.ietf.org/html/rfc7234#section-5.5.

Implementing API Deprecations

For details related to the mechanics of deprecating Learn REST APIs please email developers@blackboard.com.

Best Practices