Skip to content

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:

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.

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 according to their field type

DAM createdOn and modifiedOn, Catalog system dates (*_creation, *_modify), and changelog modified_at use UTC ISO 8601 timestamps with a Z suffix. Preserve UTC when storing synchronization checkpoints. Catalog custom attributes of type Date instead return the app's date and time without a time zone; use that form when filtering those attributes. See Filter.

Monitor contract changes

Catalog is Stable except for its explicitly marked Beta attribute-management operations; DAM is Beta. Review the 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 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 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 within the official plan limits, monitor traffic across concurrent jobs, and retry temporary failures with bounded backoff.

See 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 and 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.