# Best practices

Use these practices to build reliable and maintainable integrations with Sales Layer REST APIs.

## Use metadata endpoints

Catalog metadata endpoints describe available fields, resource structures, and relationships.

Use metadata before building dynamic requests, especially when working with products, variants, categories, attribute sets, or custom entities.

Recommended metadata endpoints include:

```http
GET https://api2.saleslayer.com/catalog/$metadata
GET https://api2.saleslayer.com/catalog/Products/$metadata
GET https://api2.saleslayer.com/catalog/Categories/$metadata
GET https://api2.saleslayer.com/catalog/Variants/$metadata
```

Cache metadata responses when possible, and refresh them when the account configuration changes.

## Minimize response payloads

Use `$select` to request only the fields needed by the integration.

This reduces transfer size, speeds up processing, and makes logs easier to inspect.

```http
GET https://api2.saleslayer.com/catalog/Products?$select=prod_ref,prod_title
```

## Filter before processing

Use `$filter` to reduce the amount of data returned by the API.

Filtering at the API level is usually more efficient than retrieving a broad dataset and filtering it client-side.

## Use pagination for large datasets

Use pagination for list operations.

For large Catalog datasets, prefer token-based pagination with `$skipToken` when the endpoint supports it and returns continuation links.

For DAM and endpoints that use offset-style pagination, use `$top` and `$skip`.

## Handle dates as UTC instants

DAM `createdOn` and `modifiedOn`, and Catalog date and date-time fields, use UTC ISO 8601 timestamps with a `Z` suffix. Preserve the time zone when storing synchronization checkpoints and convert local input times to UTC before building `$filter` expressions. See [Filter](/guides/filter#date-filters).

## Monitor contract changes

Catalog is **Stable** and DAM is **Beta**. Review the [Changelog](/changelog) for fixes and explicitly marked Beta breaking changes, including the 255-character filename limit on DAM creates. See the [REST API Evolution and Compatibility Policy](/rest-api-evolution-and-compatibility-policy) for compatibility guarantees.

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.
* Record the documented contract and maturity assumptions your integration relies on.
* Monitor the [Changelog](/changelog) before updating generated clients or request mappings.
* Test critical workflows against the OpenAPI reference before releasing integration changes.


For each changelog entry, review:

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


## Respect rate limits

Design clients to stay below documented rate limits and retry temporary failures with bounded backoff.

See [Rate limiting](/guides/rate-limiting).

## Protect credentials

API keys must be treated as secrets.

Do not expose them in browser code, public repositories, screenshots, logs, or customer-facing error messages.

See [Authentication](/guides/authentication) and [Headers](/guides/headers).

## Handle responses intentionally

Use HTTP status codes to drive client behavior:

* Treat `200`, `201`, and `204` as successful outcomes.
* Treat `400`, `401`, `403`, and `404` as errors that usually require request, configuration, or permission changes.
* Treat `409` as a state conflict, especially for DAM resources being processed.
* Treat `500` as potentially temporary, but use bounded retries.


## Build observable integrations

Log enough information to troubleshoot safely:

* API domain and endpoint.
* HTTP method and status code.
* Request timing.
* Retry count.
* Page or continuation state.
* Correlation identifiers when available.


Do not log full API keys or sensitive payload values.

## Related pages

* [Authentication](/guides/authentication)
* [Pagination strategies](/guides/pagination-strategies)
* [Rate limiting](/guides/rate-limiting)
* [Error responses](/guides/error-responses)