Integrating with a DAM API: patterns & pitfalls

Why it matters

DAM integrations fail in ways that are slow to notice. A product page shows an expired image because a webhook was dropped. A nightly sync skips assets because the result set was paged by offset while it changed. A migration job is blocked because it shares a tenant-wide rate limit with the live website connector. A retried upload creates a duplicate asset with half of its metadata. None of these is exotic: they follow directly from how HTTP APIs behave.

The HTTP standards are explicit about some of these limits. A client must not automatically retry a request with a non-idempotent method unless it knows that the request is in fact idempotent R4. 429 Too Many Requests signals rate limiting, but the standard deliberately does not define how a server identifies the user or counts requests R5, so each DAM chooses its own scope. On the security side, the OWASP API Security Top 10 lists unrestricted resource consumption, server-side request forgery and unsafe consumption of third-party APIs among the main API risks R16. All three show up in DAM integrations: bulk loads, webhook endpoints and data imported from the DAM into other systems.

The wiki documents the API surface of 20 DAM platforms, and the differences are large (see How DAM platforms support this). An integration designed around one vendor's behaviour often breaks when moved to another, which matters during a DAM migration and when choosing a DAM.

Core concepts

Recommended practices

1. Choose the authentication flow by integration type

Then answer three questions before writing code:

• Who does the integration act as? Many DAMs tie a client-credentials token to a user account, and the API returns only what that user can see. A service user with too few rights produces silent gaps; one with administrator rights is a large blast radius. Create a dedicated integration user with exactly the permissions the job needs. The guide DAM permissions, SSO & user provisioning covers the access model in more depth.
• What scopes are available? Tokens should be restricted to the resources and actions they need R3. Where the DAM's scopes are coarse, compensate with the integration user's permissions.
• How do tokens expire and rotate? Refresh tokens for public clients must be sender-constrained or rotated R3, and several DAMs rotate them on every use. If two workers refresh with the same single-use token at once, one of them is locked out. Centralise token refresh in one component, store the new refresh token before using the new access token, and alert well before long-lived refresh tokens expire.

2. Read the specification, then test against a real tenant

Where a vendor publishes an OpenAPI description, use it to generate clients, mock servers and contract tests: the format exists so that people and tools can understand an API without reading source code R10. Check which version it is, which operations it marks as experimental or beta, and whether the published file is complete. The wiki records, per platform, whether a full specification, partial fragments, a Postman collection or nothing at all is public, and stores verbatim copies of public specifications in each solution's specs/ folder.

Specifications drift from reality. Run your critical paths against a non-production tenant, keep the requests and responses as test fixtures, and re-run them when the vendor announces changes. Subscribe to the vendor's API changelog and watch for deprecation signals in responses.

3. Paginate for correctness, not just for size

Good practice for large reads:

• Use the cursor or keyset mode for anything beyond a few thousand items, and the offset mode only for user-facing browsing.
• Sort on a stable, unique key (an ID, or a modification date plus an ID as a tie-breaker). Never parse or construct page tokens: they are opaque by design R17.
• Request the maximum documented page size the API allows, but measure: very large pages can hit time-outs.
• Compare the count you received with the total the API reports (where it reports one), and log the gap.
• For exports and migrations, page over a fixed filter such as "modified before T0" so that the set does not move under you, then catch up with a delta pass.

4. Design for rate limits from day one

Rate limits shape the architecture of a DAM integration more than any other constraint. Work through them in this order:

1. Find the scope. The standard leaves it open whether limits count per credential, per resource or across the server R5, and DAMs differ widely. A per-IP budget is shared by everything behind your egress address; a per-tenant budget is shared by every integration, including the live website connector. A per-token limit lets you isolate jobs with separate credentials, if the licence allows it.
2. Find the signal. Most APIs answer 429, some use other codes, and some return an HTML error page instead of JSON when throttling. Check the Content-Type before parsing.
3. Honour Retry-After when present; it says how long to wait before the next request R4 R5. Read any rate-limit headers the API sends. An IETF draft defines standard RateLimit and RateLimit-Policy fields carrying the remaining quota and the window R6, but it is still a draft and DAM APIs use their own header names.
4. Throttle before you are throttled. Pace requests on the client side (a token bucket set somewhat below the published limit) rather than relying on rejections. Some platforms extend a block if you keep sending.
5. Back off exponentially, with jitter, and cap it. Plain exponential backoff still produces clusters of synchronised retries; adding randomness spreads them out and reduces total calls R18. Set a maximum number of attempts and a dead-letter path.
6. Retry in one layer only. If the vendor SDK already retries, do not wrap it in your own retry loop: retries multiply.
7. Spend calls wisely. Use bulk endpoints, field selection or expansion parameters, events instead of polling, and caches for static data such as metadata schemas and taxonomies. Uncontrolled consumption can lead to denial of service or higher operating costs R16, on the provider's side and on yours.

Separate monthly call allowances (a billing quota) from throttling (a speed limit). Both may apply.

5. Prefer events, and consume them defensively

Webhooks avoid polling and make integrations faster, but delivery over HTTP is at-least-once at best. Build the receiver accordingly:

• Verify authenticity. Where the DAM signs payloads, verify the signature over the raw body, using a constant-time comparison for HMAC, and reject stale timestamps to block replays R8. Where it does not sign, use what is available (secret path segments, Basic Auth over HTTPS, source IP allow-lists) and treat the payload only as a hint.
• Acknowledge fast, process later. Return 2xx quickly and put the event on a queue. Senders treat slow responses as failures and retry R8.
• Deduplicate. Use the event ID as an idempotency key R8. In CloudEvents, events with the same source and id may be treated as duplicates R9.
• Do not rely on order. Compare event timestamps or, better, re-fetch the current state of the asset before acting.
• Expect thin payloads. Many DAMs send only the asset ID and event type. Thin payloads mean an extra API call but guarantee that you act on current data R8; budget those calls against the rate limit.
• Plan for lost events. Retries are finite, and senders disable endpoints that keep failing. Monitor the subscription status, alert on disablement, and run a scheduled reconciliation that catches what webhooks missed.
• Store your subscription configuration in version control. Some platforms let you create subscriptions through the API but not read back every detail afterwards.

If the DAM has no webhooks, poll a "modified since" query at a modest interval with an overlap window, or use an event stream or audit log where the platform offers one.

6. Upload large files in parts and wait for processing

The object-storage pattern is well documented by storage providers: send parts independently and in any order, retry only the failed part, and complete the upload with the list of part numbers and their identifiers R12. Amazon S3 recommends multipart upload for objects of 100 MB or more R12. tus standardises the same idea for any HTTP server: the client asks for the current offset and continues from there R11.

• Treat pre-signed URLs as bearer secrets. Anyone holding one can use it until it expires, often more than once R13. Do not log them, and use them promptly.
• Do not build on storage internals. Bucket names, keys and storage hosts returned during upload are implementation details that vendors change.
• Clean up abandoned uploads. Incomplete multipart uploads keep consuming storage until they are completed or aborted R12; DAM upload sessions also expire. Record session IDs and part status so that a restart can resume or cancel cleanly.
• Verify integrity. Compute a checksum before upload and compare it with the value the API or storage returns, where one is exposed.
• Wait for processing. An upload is not usable until the DAM has finished generating previews and renditions and extracting embedded metadata. Poll the asset's status or listen for the "processed" event before linking it in a CMS or writing metadata that extraction might overwrite.

7. Make every write safe to retry

Network failures leave you not knowing whether a write happened. Design writes so that repeating them is harmless:

• Use external IDs. Store the source system's ID on the DAM asset (in a dedicated field) and look it up before creating. Keep a mapping table of source ID to DAM ID on your side. This is also what makes migrations restartable.
• Prefer idempotent methods. PUT and DELETE are idempotent by definition; POST is not and must not be retried automatically without another guarantee R4.
• Use idempotency keys where offered. A key sent with a POST lets the server recognise a retry and return the original result. An IETF draft tried to standardise an Idempotency-Key header, but it expired in 2025 R7; check whether your DAM supports anything equivalent rather than assuming it.
• Use conditional updates. Send If-Match with the ETag you last read so that the update fails with 412 Precondition Failed instead of silently overwriting someone else's change R4. Then re-read, merge and retry.
• Separate upload from metadata. Create or update the binary first, wait for processing, then write metadata. Each step can be retried on its own.

8. Design the sync before building it

Most DAM integrations are synchronisations: assets and metadata flowing to a CMS or PIM, or product data flowing into the DAM. Decide the following up front and write it down:

1. System of record per field. For each field, which system is authoritative, and is the flow one-way or two-way? Two-way sync of the same field needs a conflict rule. The metadata schema governance guide covers field ownership.
2. Initial load. A full paginated export over a fixed filter, with counts reconciled at the end.
3. Delta. A "modified since" query with a high-water mark you persist only after a batch succeeds, plus an overlap window to absorb clock skew.
4. Events. Webhooks or an event stream to reduce latency, never as the only mechanism.
5. Deletions and visibility changes. Delta queries on modification date usually do not return deleted or unpublished assets. Use delete events, a periodic comparison of ID lists, or the platform's audit trail. Expiry and embargo changes must reach downstream systems as reliably as new assets.
6. Reconciliation. A scheduled job that compares both sides (IDs, modification dates, checksums) and repairs drift.
7. Delivery URLs. Decide whether downstream systems store DAM delivery URLs, IDs or copies of files, and what happens when an asset is moved, renamed or replaced.

9. Handle errors, observe and secure the integration

• Parse errors deliberately. Map each status code to an action: retry (429, 503, network errors on idempotent calls), refresh the token (401), fix and stop (400, 403, 422), or re-read (409, 412). RFC 9457 defines a standard JSON error format (type, title, status, detail, instance) R15; few DAM APIs use it, so write an adapter per platform. Note that some APIs return 404 for objects the user is not allowed to see.
• Log with correlation. Record the request ID, asset ID, event ID and attempt number for every call, without logging tokens or pre-signed URLs.
• Alert on the quiet failures: webhook subscriptions disabled, refresh tokens about to expire, rising 429 counts, and reconciliation gaps.
• Do not widen access through your integration. If your middleware fetches assets with a powerful service account and serves them to end users, it must enforce object-level authorization itself; broken object-level authorization is the first risk on the OWASP API list R16.
• Validate what comes back. Data from a third-party API deserves the same validation as user input R16: file types, sizes, URLs and metadata values. If you let users register callback or import URLs, guard against server-side request forgery R16.
• Track deprecations. Note sunset dates and versioning policies in the integration's runbook, and test new API versions in a sandbox before the switch.

Common pitfalls

How DAM platforms support this

Each solution on the wiki has an API page covering authentication, token lifetimes, rate limits, pagination, uploads, events and quirks, with citations; its frontmatter summarises these points. The comparison table summarises API style, specifications and webhooks for every platform, and the wiki site's APIs overview lays out the API facts of all 20 platforms side by side. The examples below show the kind of differences this guide is about. They are illustrations, not a ranking, and the behaviour may have changed since each page's last_verified date.

Several platforms in the comparison document no webhooks, no public specification or no rate-limit figures. In those cases, polling with deltas, generous back-off and a test tenant become more important, and the gap is a good question to raise when choosing a DAM.