API integration architecture for connected enterprise systems

A resilient integration architecture depends on explicit contracts, data ownership and loose coupling. Use an API when a caller needs a request or immediate response, an event to announce a fact, a queue to absorb work, and an adapter to isolate the behaviour of an external system.

The goal is not to connect everything directly to everything else. It is to keep change local: replacing a CRM, SMS provider or partner format should not require edits in dozens of applications.

Define boundaries and ownership first

For each business entity, name the system of record: where a customer, order, payment, agreement or delivery state is created and changed. Other systems may hold a projection, but must not quietly become a second authority.

Document:

• domain and API owner;
• consumers and use cases;
• data classification;
• latency tolerance;
• availability requirements;
• contract-change process;
• retention and audit.

Avoid a universal customer object containing every field in the company. A contract should expose the minimum needed for its use case.

Synchronous request or asynchronous event

Model	Use it when	Primary risk
Synchronous API	A result is required to continue	Cascading failure and accumulated latency
Queued command	Work can complete later	The final outcome is less obvious
Event	Consumers need a fact that already occurred	Consumer incompatibility and redelivery
Batch exchange	Volume matters and latency can be high	Reconciliation and partial replay

Do not disguise a chain of five synchronous calls as one transaction. A failure at the end may not be able to undo earlier side effects. For long-running workflows, model state, compensation and eventual consistency explicitly.

A notification service, for example, can consume an order event and make its own channel decision. That design is covered in omnichannel transactional notifications.

Treat the API contract as a product

A consumer should be able to integrate without reading implementation code. The OpenAPI Specification provides a machine-readable description of HTTP APIs that can support documentation, client generation and testing.

Include:

• operation purpose and owner;
• request and response schemas;
• field requirements, formats and constraints;
• authentication and authorisation;
• success and error responses;
• rate limits;
• idempotency key and correlation ID;
• pagination and filter rules;
• versioning and retirement policy.

HTTP methods and status codes should retain their standard meaning. For machine-readable errors, RFC 9457 defines problem details with a stable type, status, human-readable explanation and occurrence identifier.

Idempotency and redelivery

In a distributed system, “exactly once” behaviour usually comes from at-least-once delivery plus idempotent processing rather than transport magic.

For a state-changing operation:

1. the client creates a key before the first request;
2. the server atomically stores the key and outcome;
3. a repeat returns the original outcome;
4. the same key with different content is rejected;
5. retention covers the complete retry window.

For events, persist processed message IDs or rely on an appropriate unique business constraint. A handler must safely receive the same event after a restart.

These controls are especially important for irreversible external side effects such as messaging, as explained in SMPP versus HTTP API.

Transactional outbox closes the dual-write gap

If an application commits its database change and then publishes an event, a crash between the two leaves data without its event. Publishing first has the opposite flaw: consumers may see a fact that is not committed.

A transactional outbox stores the business change and event in one database transaction. A separate publisher reads the outbox and sends to the broker. Publishing can still repeat, so consumers remain idempotent.

An inbox or processing ledger on the consumer side supports deduplication, audit and controlled replay after a defect is fixed.

Adapters protect the domain

An external system may expose unstable fields, SOAP, CSV, SMPP or a proprietary status model. An adapter translates that contract into the internal language and keeps provider details out of domain logic.

A strong adapter owns:

• authentication and credential rotation;
• schema and status mapping;
• timeouts, retry and circuit breaking;
• rate limiting;
• correlation and safe logs;
• dependency metrics;
• a test stub.

Packaged enterprise examples appear in our guide to SMS integration with 1C and Bitrix24.

Versioning without permanent v1 and v2

Prefer backward-compatible evolution: add an optional field, introduce a new value with agreed fallback, or add an endpoint. Removing, renaming or changing meaning needs a new version or a compatibility period.

A sound change process:

1. publishes a proposal and impact analysis;
2. runs contract tests;
3. gives consumers a migration deadline;
4. measures old-version use;
5. retires it after confirmation.

A version number in the URL does not manage the lifecycle. Without a consumer registry, the provider cannot know who a shutdown will break.

API security

Apply least privilege: a service receives only the operations and data it needs. Do not share one indefinite credential across environments and consumers.

Baseline controls:

• TLS and certificate verification;
• separate service identities;
• scopes or roles;
• short credential lifetime and rotation;
• rate and request-size limits;
• schema validation;
• audit of administrative and sensitive operations;
• personal-data masking;
• rapid revocation procedure.

Critical integrations should be included in the threat model and the data-protection requirements applicable to the information system.

Integration observability

Propagate a correlation ID through HTTP, messages and background work. Measure:

• rate, errors and duration by operation;
• queue age and retry count;
• permanent-failure ratio;
• event-to-business-outcome latency;
• failures by external dependency;
• API version use;
• dead-letter queue depth.

Log the decision, not the secret: contract, version, identifier and error class. Our infrastructure observability guide describes how to connect metrics, logs and traces.

Architecture review checklist

• Every key entity has a system of record.
• Every contract has an owner and known consumers.
• Sync or async follows the latency requirement.
• Timeouts fit inside the user’s time budget.
• Retry is bounded and duplicate-safe.
• Critical event publication uses an outbox.
• Errors are machine-readable and expose no internals.
• Contract tests validate schemas.
• Credentials are isolated by environment and rotate.
• Queues and DLQs have owners and runbooks.
• Old-version use is measured before retirement.

Next step: Logic Telecom can help define integration contracts, adapters and event flows. Begin with one critical process: name the system of record, latency budget and failure behaviour for every dependency.