# Versioning and compatibility

This page explains how to read API versions, compatibility expectations, and changelog entries in this documentation.

## Current documented versions

The current references published in this site are:

| API                      | Current reference                           |
|--------------------------|--------------------------------------------|
| DAM REST API             | [DAM REST API v2.0](https://docs.api.saleslayer.com/apis/dam-v2.0)          |
| Catalog REST API         | [Catalog REST API v2.0](https://docs.api.saleslayer.com/apis/catalog-v2.0)      |

Use the API overview pages for functional context and the OpenAPI references for endpoint-level details.

## Compatibility expectations

Versioned references describe the API behavior documented for that version.

Changes are usually considered compatible when they add functionality without requiring existing clients to change. Examples include:

- Adding a new endpoint.
- Adding an optional request field.
- Adding a response field that clients can safely ignore.
- Adding a new documented status code for a behavior that already existed.
- Improving examples or descriptions without changing API behavior.

Changes may require integration review when they affect existing requests or assumptions. Examples include:

- Removing or renaming an endpoint.
- Removing or renaming a request or response field.
- Changing required fields.
- Changing validation rules for existing fields.
- Changing pagination, filtering, or sorting behavior.

## Client recommendations

Build integrations so they tolerate compatible additions:

- Ignore unknown response fields unless your workflow explicitly needs them.
- Validate only the fields your integration depends on.
- Store API version assumptions in integration documentation.
- Monitor the [Changelog](https://docs.api.saleslayer.com/changelog) before updating generated clients or request mappings.
- Test critical workflows against the OpenAPI reference before releasing integration changes.

## Changelog usage

Use the changelog to understand documented changes over time.

For each new version, review:

- Added, changed, or removed endpoints.
- Status code changes.
- Request and response schema changes.
- Validation behavior.
- Documentation corrections that affect implementation.