Skip to content
← All articles
6 min read

API design for integrations: building reliable interfaces for external systems

Effective API design for integrations focuses on predictable synchronization, automated error recovery, and long-term contract stability. When external services connect to your platform, the API must handle partial failures, heavy datasets, and continuous changes without breaking existing workflows.

Pagination: why cursor-based pagination fits integrations better than offset

Offset pagination with limit and page parameters works for simple user interfaces, but it degrades quickly during automated synchronization. When records are created or deleted while a client paginates through large tables, offset shifts cause records to be either duplicated or skipped entirely. In addition, deep offsets force the database to scan and discard thousands of unneeded rows before returning a page.

Cursor-based pagination solves these problems by using a stable pointer, such as a compound key of a timestamp and a unique record identifier. The client receives a next_cursor value with every page and requests the next batch relative to that specific record, ensuring deterministic traversal regardless of concurrent writes.

Incremental sync using updated_at filters and deletion tracking

Integrations should rarely perform full data dumps after the initial export. Providing filters such as updated_at_gte and updated_at_lte allows external systems to poll or fetch only records that were created or modified since the last successful sync cycle.

A frequent challenge in incremental sync is accounting for deleted entities. If a row is deleted directly from the database, an updated_at query will never surface it to the client. Supporting soft deletes with a deleted_at flag or exposing a dedicated deleted records endpoint ensures integrated systems can prune stale records reliably.

Versioning without breaking existing clients

API contracts change as business domains evolve, but breaking changes must not disrupt running production integrations. The most reliable approach is URL path versioning or request header versioning, keeping the contract explicit for every caller.

Non-breaking additions, such as optional request fields or new properties in the response payload, should be supported within the current version. Whenever a breaking change is unavoidable—such as renaming fields, altering types, or changing status flows—introduce a new version while supporting the previous version during a deprecation window.

Unified error structure and machine-readable error codes

Integrations are consumed by code, not humans. Standard HTTP status codes are necessary, but they are not sufficient on their own. A 400 Bad Request or 422 Unprocessable Entity must return a structured JSON envelope containing a machine-readable error code, a human-readable message, and field-level validation details.

  • A standardized error code string that clients can use in switch statements without parsing English text.
  • A list of validation issues identifying the exact field path and the constraint that was violated.
  • A unique request identifier header to trace the failed transaction across application logs.

Managing traffic with rate limits and explicit retry headers

Rate limiting protects core services from sudden traffic spikes and poorly configured polling loops. Limits should be enforced per token, per IP, or per tenant, depending on the authentication model.

When a client exceeds the limit, return HTTP status 429 Too Many Requests along with standard headers such as Retry-After, X-RateLimit-Limit, and X-RateLimit-Remaining. This provides client libraries with the exact interval to wait before reattempting the request, avoiding aggressive retry storms.

Complete documentation and realistic payload examples

A formal specification, such as an OpenAPI document, provides a single source of truth for request and response schemas, authentication mechanisms, and expected status codes. It also allows developers to generate client libraries or mock servers for testing.

Specifications must be accompanied by realistic examples of full request bodies and responses, including both success responses and error envelopes. Abstract placeholders often hide required formatting details, such as date formats or enum values, leading to integration bugs.

Questions

FAQ

Didn't find an answer — ask on the call or in Telegram.

When is offset pagination acceptable instead of cursor pagination?

Offset pagination is acceptable for small, static datasets or admin interfaces where users jump directly to arbitrary page numbers. For recurring background integrations and tables that change frequently, cursor pagination remains the standard.

How should webhooks and polling interact in integration APIs?

Webhooks notify external systems immediately when an event occurs, while polling with updated_at filters serves as a fallback to recover missed events during network outages or webhook delivery failures. Using both together ensures fast updates and reliable consistency.

Why should error codes be strings instead of numeric identifiers?

String error codes, such as invalid_currency or payload_too_large, are self-documenting in logs and source code. They reduce ambiguity, avoid conflicts between modules, and eliminate the need to look up arbitrary numeric mappings during debugging.

Related service

CRM, ERP and API integrations built for your workflows

When teams copy data between systems by hand, delays and mistakes become part of the process. We automate the exchange and make its status visible to the people running it.

Learn about the service
Other articles
Contact

Shall we discuss your task?

Thirty minutes on a call — and you understand the architecture, timeline and engagement format. No obligations.

Or message us on Telegram →Follow our Telegram channel →

Enter your Telegram or email so we can reply.

We reply within 15 minutes.