API-first architecture: why it’s no longer optional for a PIM

An API is not just a box to tick on a comparison grid. Between a PIM whose interface utilises its own public API and a PIM to which a few REST endpoints tacked on to handle requests for quotes, the difference is measured in weeks of integration and production incidents. Here are the criteria for assessing a PIM API before signing on the dotted line, and what goes wrong when these safeguards are missing.

What ‘API-first’ means, and what it doesn’t mean

API-first means that the API contract is the product: the web interface is just one client amongst many. Three verifiable consequences follow from this — any operation accessible via the interface is also accessible via the API, validation rules reside on the server side rather than within the form, and the interface authenticates using the same scope model as that provided to integrations.

What this does not mean is: ‘we have an API’. A layer added as an afterthought is quickly recognisable: it bears the hallmarks of its origin, often an export to an e-commerce site. An arbitrary subset of fields, partial data entry, pagination that breaks as soon as you enter data in parallel, a lack of webhooks, and documentation without a single runable example.

Four checks are enough to tell the difference from the outside:

• Open the development toolsduring the demonstration. If the interface calls publicly documented routes, the API is the foundation of the product. If it calls internal routes not listed in the reference, the public API is an add-on, and it will fall behind.
• Test the coverage against your actual operations: create an attribute, publish to a channel, import a batch. Look for these in the documentation, under ‘write’ operations.
• Read the API change log.If it does not exist or is conflated with the product’s release notes, no one is tracking breaches of contract.
• Check access to the documentation.If your developers have to go through a sales representative to read it, they won’t be able to cost the integration before signing the contract.

To give an idea of the scale: Pixee PIM exposes 530 API endpoints, freely accessible at apidoc.pixeepim.com. The number is not an argument in itself — the following explains why.

What a proper API must offer

Consistent pagination and filtering

Offset pagination (offset and limit) is the most common source of error in large catalogues: as soon as a concurrent write operations inserts or deletes a row, the subsequent pages shift, causing you to skip over or duplicate products without realising it. Opaque cursor pagination eliminates the problem. Also insist on deterministic sorting — sort key supplemented by the identifier as a tie-breaker —, a specified maximum page size and consistent filters across all collections. The test: browse the entire catalogue whilst writing in parallel, then count the distinct items.

Idempotent writes

Your client sends a POSTrequest, but the connection is lost before a response is received. The creation may have taken place. Without idempotence, the only options are to retry and create a duplicate, or not to retry and lose the data. Two acceptable responses: a header Idempotency-Key which the server stores to replay the original response, or a PUT per stable business key (SKU, GTIN) that creates or updates. Ask how long the keys are retained, and what the server responds with if the same key is sent again with a different body: a 409— not a silent second creation.

Batch operations

Importing one hundred thousand product references at a rate of one call per product is not feasible: the duration is dominated by round-trip latency, and even the slightest throughput limit causes the processing window to balloon. You need either entry points that accept multiple objects per request with a status returned line by line — rather than a single 400 which invalidates the entire batch — or an asynchronous mode: you submit the batch, receive a task ID, track its progress, and retrieve an error report. Check the maximum batch size and the behaviour in the event of . At Pixee PIM, these long-running processes are handled by 12 Celery workers spread across 14 queues, so that a bulk import does not block the synchronisation of a channel.

Advertised throughput limits and quota headers

Every API has limits; the question is whether they are documented. A usable API returns the limit, the remaining balance and the reset date (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset), and includes 429 one with Retry-After. Without these headers, your client can only slow down at random. Ask whether the limit applies per key or per organisation, and whether it differs depending on the type of call. Pixee PIM applies 23 distinct limitation levels depending on the nature of the call.

Actionable error codes

The worst anti-pattern remains the 200 accompanied by a body indicating a failure: monitoring tools, proxies and HTTP libraries count it as a success, and the failure becomes invisible. A proper API distinguishes between 400 (malformed request) from the 422 (valid request, data rejected), flags conflicts in 409, and returns a structured body: a stable, machine-readable code, a human-readable message, a pointer to the faulty field, and a correlation ID to quote when contacting support. Your client then knows what needs to be retried (429, 503) and what ends up in the permanent error queue.

Versioning and deprecation policy

It matters little whether the version is in the path or in a header. What matters is that a written rule defines what constitutes a breaking change: removing a field, restricting an enumeration or changing a type are breaking changes; adding an optional field is not, provided clients are required to ignore unknown fields. Require a pre-announced deprecation window, headers Deprecation and Sunset on the affected routes, and a dated log. Without these, every version upgrade becomes an unplannable risk.

Authentication and token scope

One key per integration; never share a key between the ERP connector, the e-commerce site and a service provider’s scripts. This requires sufficiently granular scopes so that a marketplace connector with catalogue-reading access cannot modify users — Pixee PIM distinguishes between 13 of these. Also check for seamless rotation (two valid keys at the same time), expiry and traceability of each key. The same reasoning applies to keys you provide yourself, as detailed in our article on the BYOK model and AI API keys.

Webhooks: why periodic polling isn’t enough

Querying the API at regular intervals leads to a lose-lose situation: too often, you use up your quota only to find that nothing has changed; not often enough, your channels display out-of-date data. Furthermore, polling is poor at detecting deletions, which only become apparent by comparison with a reconstructed complete state. Webhooks reverse the flow, at the cost of four constraints you need to be aware of before writing the consumer.

• At least-once delivery— the same event may occur twice (re-transmission after a timeout, node failover). Your reception point must be idempotent: retain the identifiers of processed events and ignore duplicates.
• Message signing— each message must carry an HMAC signature calculated on the raw body and a timestamp. Verify it before deserialising, using a constant-time comparison, and reject messages that are too old to prevent malicious replay attacks. Without a signature, your public URL will accept any price update from anywhere.
• Replay— your receiver will be unavailable at some point. Does the publisher re-attempt, with what lookback period and for how long, and can you manually replay a period? Otherwise, even the slightest outage requires a complete resynchronisation.
• Order not guaranteed— two changes to the same product may arrive in the wrong order. Therefore, treat the event as a notification (“this product has changed”) and retrieve the current state via the API, or compare a version number and ignore any events older than the one you have applied. Never apply the contents of a webhook as a blind delta.

A real-world example: an ERP, an e-commerce site and three marketplaces

Typical topology for a retailer: the ERP system controls prices and stock levels, the PIM system controls content, and four systems consume the catalogue — the e-commerce site and three marketplaces, each with its own mandatory attributes per category. Details of the connectors can be found on the integrationspage. Here’s what goes wrong when the upstream API is substandard.

One principle sums up this picture: even with reliable webhooks, maintain a scheduled reconciliation that compares the PIM’s state with that of each channel — this is the only safety net that catches a missed event during an incident. The operations covered are described on the featurespage.

As an aside: an API with a stable contract and fine-grained scope lends itself naturally to exposure to agents. Pixee PIM publishes 8 MCP (Model Context Protocol) servers and 42 JSON-RPC 2.0 endpoints, all governed by the same authentication rules. This is not a selection criterion in itself, but rather an indicator: this layer is not built on top of an API that has been cobbled together after the fact.

What to ask for during the evaluation

• Public documentation, accessible without an account and without having to go through a sales representative: your developers need to estimate the integration workload before the decision is made.
• Aseparatetest environment, with disposable data and the same throughput limits as in production. An unrestricted sandbox tells you nothing about what your connector will actually experience.
• Executable examples: commands curl that can be copied and a valid OpenAPI specification. Generate a client from the specification and call three routes; if the generation fails, the specification is merely for show.
• A log of API changes, dated and separate from the product’s release notes, showing what has been deprecated and when.
• A named technical contactand a response time committed to in writing.

The best pre-sales investment remains a real-world scenario played out in the test environment: create a number of products, modify some of them, delete a few, then observe what your channels receive and any discrepancies.

Frequently asked questions

Is a GraphQL API better than a REST API for a PIM?

The interface style matters less than the guarantees described above. GraphQL offers fine-grained field selection and standardised cursor-based pagination, but complicates throttling — counting requests no longer makes sense; a cost per request is required — and HTTP caching. Idempotence, batch operations, signed webhooks and deprecation policies remain essential in both cases.

How many entry points are required for a PIM?

The number on its own is meaningless: an API can expose many and still be unusable for write operations. The useful question is the coverage of your own operations. List the actions you intend to automate and identify their equivalents for creation, update and deletion. Pixee PIM publishes 530 of them, but it is the publicly available reference that answers your question, not the total number.

Can we do without webhooks if we use night-time synchronisation?

Yes, in one specific scenario: a stable catalogue, a single channel, and a one-day tolerance regarding data freshness. As soon as prices or stock levels change, or where multiple channels need to remain consistent with one another, the latency gap becomes a business issue. Conversely, even with webhooks, ensure you carry out periodic reconciliation.

Should you require an availability commitment for the API?

First, ask what is measured and published: an accessible status page, a history of incidents, and a notification when a service degrades. A quantified commitment without a public measurement tool is a clause that is difficult to enforce. Also ask how maintenance windows are announced and what happens to batch jobs that are in progress during these windows.