API fundamentals
Build integrations that remain reliable
Apply these patterns to every operation, then use the generated API reference for its exact parameters, response schema, and constraints.
Authentication #
Send the API key only from trusted server-side code using the authentication scheme documented for the selected operation. Store credentials in a secret manager, scope each key to one integration, rotate keys on a schedule, and revoke them when an integration ends.
Idempotency #
Assume a network timeout can occur after the API accepts a write. Generate and persist a unique client request ID before each create or update, reuse it for retries when the operation documents idempotency support, and reconcile the resulting resource before sending a new write.
Pagination #
Use only the page, cursor, and page-size fields exposed in the operation’s parameter table. Keep filters and sort order stable for a full traversal, checkpoint progress after every page, and stop at the response’s documented final-page indicator.
Filtering and sorting #
Validate filters before sending them and prefer narrow date ranges for large collections. Use documented filter names and enum values exactly as published. Record the selected filters and ordering with the sync checkpoint so a retry reads the same result set.
Errors and retries #
Log the HTTP status, response body, operation, and correlation ID without logging credentials or sensitive payload fields. Correct invalid requests before retrying 4xx responses. Retry transient failures with exponential backoff and jitter, then route exhausted retries for review.
Rate limits #
Limit concurrent calls, respect a documented retry delay or Retry-After response header, and reduce page size or polling frequency when your workload approaches a service limit. Queue background work instead of retrying immediately in a loop.
Versioning and deprecations #
Pin your integration to the documented API version, track the downloadable OpenAPI contract in source control, and review contract changes before deployment. Treat a deprecated operation as a migration task and test its replacement before the published retirement date.