# REST API Evolution and Compatibility Policy

## Purpose

Sales Layer REST APIs are designed to provide customers and partners with a predictable and stable integration contract while allowing the platform to continue evolving.

This policy defines how Sales Layer manages API compatibility, maturity levels, breaking changes, Beta surfaces, bug fixes, and the communication of API changes.

The public API documentation and the API **[changelog](/changelog)** are the official references for the supported behavior and evolution of the Sales Layer REST API.

## API surfaces

Sales Layer applies compatibility guarantees to **API surfaces**.

An API surface is a publicly documented part of the REST API with a defined compatibility contract. An API surface may represent:

- an entire API;
- a functional capability or resource group;
- a related set of endpoints;
- or, when necessary, an individual operation.


This means that maturity does not necessarily apply to an entire API as a single unit.

For example, an API may be generally Stable while introducing a new capability as Beta. The Beta status applies only to the explicitly identified surface and does not change the compatibility guarantees of the existing Stable surfaces.

Unless otherwise indicated in the documentation, an API operation inherits the maturity level of the surface it belongs to.

## API maturity levels

Sales Layer distinguishes between **Stable** and **Beta** API surfaces.

| Surface status | Compatibility policy |
|  --- | --- |
| **Stable** | The published contract of the surface is preserved. Sales Layer does not introduce breaking changes to Stable surfaces. Evolution must remain backward compatible. |
| **Beta** | The contract of the surface is public and documented, but it may still evolve. Breaking changes may occur within that Beta surface and will be identified in the **changelog**. |


The maturity status of an API surface is indicated in the corresponding API documentation.

A Stable API may contain newly introduced Beta surfaces. Those Beta surfaces must be explicitly identified and do not alter or reduce the compatibility guarantees of existing Stable surfaces.

## Stable API surfaces

Stable API surfaces are considered part of the supported public API contract.

Sales Layer may continue to extend and improve Stable surfaces, but existing valid integrations must remain compatible.

Examples of backward-compatible evolution include:

- adding new endpoints;
- adding new optional capabilities;
- adding optional request parameters;
- adding new fields without modifying the meaning of existing fields;
- introducing new resources or operations;
- extending existing capabilities in a backward-compatible way;
- fixing defects while preserving the documented contract.


Sales Layer does **not introduce breaking changes to Stable API surfaces**.

When a new capability cannot be introduced without changing an existing Stable contract, Sales Layer will use an alternative approach that preserves the existing behavior, such as introducing a new endpoint, operation, resource, or separately identified API surface.

The existence of a Beta surface within the same API does not allow changes that would break an existing Stable surface.

## What is considered a breaking change?

A breaking change is an intentional modification to the published contract of an API surface that can cause an existing valid integration to stop working or behave differently.

Examples include:

- removing or renaming an existing field;
- changing the structure of an existing response;
- making a previously optional request field mandatory;
- changing the documented meaning or semantics of a field;
- removing an existing endpoint or supported operation;
- reducing a documented capability in a way that invalidates previously valid requests.


Breaking changes are not permitted in **Stable API surfaces**.

They may occur within API surfaces explicitly marked as **Beta**, where the contract is still evolving.

The Beta status applies only to the surface identified as Beta. It does not extend to other Stable resources or operations simply because they belong to the same API.

## Beta API surfaces

Beta API surfaces are publicly available and documented, but their contract has not yet reached the same compatibility guarantees as a Stable surface.

A Beta surface may represent an entire API or a specific capability, resource group, set of endpoints, or operation within a larger API.

During the Beta phase, Sales Layer may modify elements of that Beta surface, including:

- resource structures;
- request or response schemas;
- endpoint behavior;
- supported query capabilities;
- field semantics;
- other elements of its public contract.


When a Beta release introduces an incompatible change, the change will be identified as a **breaking change** in the API **changelog**, together with a description of the affected surface and behavior.

Consumers using Beta surfaces should therefore review the **changelog** regularly while integrating with those capabilities.

A Beta surface may graduate independently to **Stable** when its contract is considered sufficiently mature. Other surfaces within the same API are not required to share the same maturity level.

## Coexistence of Stable and Beta surfaces

Stable and Beta surfaces may coexist within the same API.

For example, a Stable API may expose established product-management capabilities as Stable while introducing a new metadata capability as Beta.

In this situation:

- existing Stable surfaces retain their full compatibility guarantees;
- the Beta status applies only to the explicitly identified Beta surface;
- breaking changes are permitted only within the Beta contract;
- a change in the Beta surface must not be used to justify breaking an existing Stable surface;
- documentation must make the maturity status of the Beta surface clear.


This allows Sales Layer to introduce and refine new capabilities without reducing the stability guarantees of existing integrations.

## Bugs and bug fixes

A bug occurs when the implementation of an API surface does not behave according to its documented contract.

For example:

- a documented operation returns an unexpected server error;
- a supported filter does not work correctly;
- pagination skips or duplicates records;
- a field does not contain the value or format defined by the API contract;
- an update operation reports success but does not correctly apply the requested change.


A bug fix restores the expected API contract and is therefore **not considered a breaking change to the contract**.

In some cases, consumers may have adapted their integration to an unintended or incorrect behavior. Correcting that behavior may therefore produce an observable change, but the purpose of the fix is to restore the documented API behavior.

Relevant fixes are recorded in the **changelog**.

## Undocumented behavior

Behavior observed in the API is not automatically part of the supported contract unless it is documented as such.

Applications should not rely on incidental implementation details that are not guaranteed by the public API documentation.

For example, if an endpoint happens to return records in a particular order but no ordering guarantee is documented, that order should not be considered part of the API contract.

When a particular behavior is important for an integration, the public API documentation should be used as the reference for determining whether that behavior is supported.

## Communication of API changes

The Sales Layer REST API **changelog** is the official channel for publishing relevant API changes.

The changelog includes, where applicable:

- new API capabilities;
- relevant functional changes;
- bug fixes;
- documentation changes;
- Beta API surface breaking changes;
- maturity changes, such as a Beta surface becoming Stable;
- other changes that may be relevant to API consumers.


When a change affects a Beta surface, the **changelog** identifies the affected surface so that consumers can distinguish it from Stable parts of the same API.

For Beta surfaces, incompatible changes are explicitly identified as **breaking changes**.

Additional communication may be provided when Sales Layer considers that a change requires specific coordination or action from affected customers.

## Source of truth

The supported API contract is defined by the public Sales Layer REST API documentation, including:

- the published OpenAPI specification;
- endpoint documentation;
- documented field semantics and API conventions;
- the maturity status of the relevant API surface;
- the API **changelog**.


Where different maturity levels coexist within the same API, the status explicitly documented for the most specific applicable surface determines its compatibility policy.

The current REST API documentation and changelog are available at:

[https://docs.api.saleslayer.com/](https://docs.api.saleslayer.com/)

## Summary

| Situation | Sales Layer policy |
|  --- | --- |
| New compatible capability | Allowed |
| New endpoint or resource | Allowed |
| New optional field or parameter | Allowed when backward compatible |
| Stable and Beta surfaces within the same API | Allowed |
| Breaking change in a Stable surface | Not allowed |
| Breaking change in a Beta surface | Allowed within that Beta surface and documented in the **changelog** |
| Beta surface inside a Stable API | Allowed; Stable surfaces retain their existing guarantees |
| Promotion from Beta to Stable | May occur independently for an API surface |
| Bug | Implementation does not comply with the documented contract |
| Bug fix | Restores the documented contract |
| Undocumented implementation behavior | Not automatically part of the supported contract |
| Official record of API evolution | API **changelog** |


> **Stable API surfaces evolve without breaking their published contract. Beta surfaces may evolve their contract while they remain in Beta. Stable and Beta surfaces may coexist within the same API, and the presence of a Beta surface does not reduce the compatibility guarantees of existing Stable surfaces. The API documentation and changelog are the authoritative references for supported behavior and API evolution.**