API compatibility policy and deprecation policies
Compatibility policy
Wherever possible, REST resources and their representations are maintained in a manner that is compatible with earlier versions. If it is necessary to change the contract in a way that is not compatible with earlier versions, a new resource, media type, or version is created with the new representation. The old resource or media type is maintained in accordance with the API deprecation 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 asGetFoo(String param)
. This change can cause a breaking change on the client because the logic that was embedded inGetBar
is no longer invoked. - A current path /v1.0/foo/bar might result in client-generated code
GetBar
andGetBarAsync
. The addition of an API /v1.0/foo/Async conflicts with this generated code.
- An API exists /v1.0/foo/bar. The code generator might generate
- 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-definedenum
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-existentenum
values by, for example, making a request with an invalidenum
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. ThismessageId
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 previoustype
and respond with the previoustype
, 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
- Notice of deprecation
- Notice of API deprecation are issued through the following channels at least 12 months before
the proposed end of life date.
- Swagger
- Swagger defines the API contract to consumers. The APIs that are being deprecated are marked
with the tag
deprecated
. - Sunset API HTTP response header
- The APIs that are being deprecated return a
Sunset
HTTP response header that indicates the date that the resource becomes unavailable. TheLink
HTTP response header provides a URI to the API sunset policy information. Monitor the API calls for theSunset
HTTP response header to allow sufficient time to migrate from the deprecating API. - IBM Documentation
- The "What's new" section contains a notification about the deprecation with links to more detailed information. The information shows the API, the deprecated version, the replacement version, and the end of life date. The notification continues until the APIs reach the end of life date.
- Deprecation date
-
- Any IBM Documentation content that is now redundant is removed.
- All Swagger documentation for the deprecated APIs is removed or hidden.