API Lifecycle

Pre-Release APIs

These APIs are not recommended for production use.

We do however encourage you to try them out and provide feedback.

All gRPC methods marked with a beta status or having major version zero are considered pre-release.

This is an example of a gRPC method marked as beta:

service MyService {
  rpc MyMethod(MyMethodRequest) returns (MyMethodResponse) {
    option (status) = BETA;
  }
}

New functionality will typically be released as a pre-release API. During this period, we will gather feedback and make changes based on that feedback.

When we are confident that the API is stable and fulfills our requirements, we will release it as a stable version by removing the beta status.

It is important to note that we may make breaking changes to pre-release APIs without notice. This allows us to iterate quickly and make changes based on feedback from our customers.

It is not guaranteed that a pre-release API will be released as a stable version, and they can be removed at any time.

Versioning and Backward Compatibility

Once a API is released as a stable version, the API will be maintained in a backward compatible way. This means that we will not remove or change existing fields, methods or services in a way that breaks existing clients.

If we need to make a change that is not backward compatible, we will release a new version of the API.

What is a Breaking Change?

For our gRPC APIs, we will not make any changes to the wire format or JSON encoding that breaks existing clients.

It is important that code is written in a way that is resilient to new fields being added to responses, and that clients do not rely on the order of fields in a response.

As an example, adding a new enum value to a non-critical field is not considered a breaking change but that may break clients that are not resilient to new enum values (e.g. not using a else branch in a switch statement).

For more information about backward compatibility and breaking changes, see the following resources:

• https://buf.build/docs/breaking/rules/

Deprecation Policy

We will deprecate APIs that are no longer recommended for use. A deprecation notice in the API documentation, and all users of the API will be notified.

All deprecated APIs will be maintained and fully supported until the deprecation period has ended.

If applicable, we will provide a migration path to a new API.