Tag: Integration

The API section of the demo lasts four minutes. Someone fetches a product, the JSON looks reasonable, everyone nods. Six months later you are writing a script that pages through eleven thousand products every night because there is no way to ask what changed.

The four minutes were not enough. Here is what to ask instead.

Short answer: eight questions decide whether an integration will be pleasant or permanent employment. Can it express your variant structure, can it tell you what changed since a point in time, can it page deterministically, can it write in bulk, is it idempotent, does it push events, does it expose the completeness state, and can you get everything out. Ask them before the contract, in writing.

One: can the API express what the interface shows?

This sounds absurd and it is common. A platform whose interface presents a family, a product and its variants may expose an API that returns a flat list of sellable items with the parent relationship implied by a shared prefix.

Test it with your own worst case, not with their sample data. Take the most awkward product you have, the one with three variant axes and an incomplete grid, and ask them to model it and show you the API response. If the response cannot round-trip that structure, everything you build on top will be flattening and re-inflating it, which is where data goes to get lost. The structure this has to survive is described in attributes, variants and the SKU problem.

Two: how do you ask what changed?

The single most consequential question, and the most often answered badly.

You want a change feed: give it a timestamp or a cursor, get back everything modified since, including deletions. What you often get instead is a filter on a modified_at field, which is nearly the same thing and fails in two ways. It misses deletions entirely, because a deleted record has no row to carry a timestamp. And it misses records whose modification was caused by a related record changing, unless the platform propagates timestamps, which most do not.

Ask specifically: does a change to a variant update the parent’s timestamp? Does a change to a shared attribute update every product using it? If the answer is no to either, your incremental sync will silently miss updates and you will discover it through a customer.

Three: is pagination deterministic?

Offset pagination over a changing collection loses and duplicates records. It is not a subtle failure; it is arithmetic. If a record is inserted before your current offset between page four and page five, one record is skipped, permanently, with no error.

You want cursor or keyset pagination, where the cursor encodes a position in a stable ordering. Ask what happens when a record is inserted mid-traversal. A good answer describes the guarantee. A vague answer means offsets.

Also ask about the page size ceiling and the rate limit together, because they multiply. A hundred records per page against sixty requests a minute means six thousand records a minute, which is fine at ten thousand products and not fine at two hundred thousand.

Four: can you write in bulk, and what happens halfway through?

Loading a catalogue one record at a time is slow enough to matter during migration and during any bulk correction.

Two properties to establish. Whether there is a bulk endpoint that accepts many records in one call, and what its failure semantics are. A bulk call that fails atomically is easy to reason about. One that applies the first four hundred of five hundred records and returns a partial error is workable if it tells you precisely which ones. One that returns a generic failure after partial application is the worst case, and it is common.

Ask for the shape of the error response before you believe the answer.

Five: are writes idempotent?

You will retry. Networks fail, jobs get rerun, someone double-clicks.

An idempotent write means sending the same request twice leaves the same state as sending it once. The usual mechanism is an upsert keyed on your identifier, or an idempotency key you supply. Without one, a retry creates a duplicate, and duplicates in a product catalogue are unusually expensive because they propagate to channels before anyone notices.

This is also the reason to key writes on your own stable identifier rather than on the platform’s internal one. Your identifier exists before the record does, which is what makes upsert possible.

Six: does it push, or must you poll?

Polling a catalogue for changes is a cost you pay forever, and its latency is bounded by how often you are willing to pay it.

A platform that emits webhooks on create, update, delete and state change lets you react in seconds and stop scheduling anything. Ask about the delivery guarantees rather than just the feature: is delivery at least once, is there a retry policy, is the payload signed, and does the event carry enough to act on or only an identifier you must then fetch.

At-least-once delivery is normal and fine, provided your handler is idempotent, which is the same property as question five viewed from the other side.

Seven: is the completeness state readable?

The completeness model is the reason to buy a product platform at all, so it is worth checking that the number is available outside the interface.

You want to query “which products are not ready for channel X, and which fields are missing”. If that exists only as a dashboard, you cannot build it into your own operational tooling, cannot alert on it, and cannot include it in a launch checklist that runs automatically. The operational value of that query is set out in running product content as an operation.

Eight: can you get everything out?

Ask it plainly. Can we export every record, every relationship, every version and every asset association, in a documented format, through the API, without a support ticket.

The answer sets your exit cost, and it is the question that most reliably distinguishes vendors who expect you to stay because you want to from those who expect you to stay because you cannot leave. A confident answer is a good sign about everything else.

What about the general shape of the API?

Less important than the eight above, but worth noting.

REST with sane resources is fine and is what most of this category ships. GraphQL is pleasant for read-heavy front ends because it avoids over-fetching, and Shopify’s admin API is a well-documented example of the style if you want to see one. Neither choice determines whether the integration will work; the change feed and the pagination do.

Authentication should be OAuth 2.0 or scoped API keys with the ability to issue and revoke per integration. A single shared key with full access is a finding waiting to be written up.

Custom fields deserve one specific question: are they first-class in the API, with the same query and filter capability as built-in fields, or are they a bag attached to the record? Shopify’s metafields are a reasonable reference point for what first-class looks like. If your extensions are second-class, everything specific to your business will be the slow path.

How should you actually run this evaluation?

Not as a questionnaire. Ask for a sandbox account and spend a day writing the smallest real integration: load fifty of your own products including the awkward one, change three of them, and pull the changes incrementally. That day answers six of the eight questions honestly, and it answers them about your data rather than theirs.

The answers then feed directly into the integration design in wiring a DAM to a PIM and into the field ownership list in single source of truth applied to product data. The equivalent set of questions for the asset side is in DAM for developers.