What Is API-to-API Integration? Patterns and Examples

API-to-API integration is the controlled exchange of data or commands between two software interfaces. One service may call another synchronously over HTTP or gRPC, publish an event for asynchronous consumers, receive a webhook, or participate in a longer workflow coordinated by an integration service or workflow engine.

The right design is not always an API gateway in the middle and not always a direct connection. It depends on latency, consistency, failure handling, ownership, and whether the interaction is north-south client traffic or east-west service communication.

Key Takeaways

• Direct service calls are appropriate when the dependency is intentional, observable, and resilient.
• Use asynchronous messaging when the caller should not wait for every consumer to finish.
• Authenticate the workload, authorize the operation, validate all external data, and protect credentials.
• Retry only bounded, transient, and repeatable operations; use idempotency for side effects.
• An API gateway centralizes routing and cross-cutting policies but is not a general workflow engine.
• Put business sequencing and durable state in an application, integration service, or workflow system that owns that behavior.

How API-to-API Integration Works

At minimum, an integration has a producer or caller, a contract, a transport, and a consumer. Production designs also need identity, policy, failure handling, observability, and lifecycle ownership.

flowchart LR
    A[Calling application] -->|Request or event| B[Integration boundary]
    B --> C[Receiving API or consumer]
    C -->|Response or outcome| B
    B --> A
    A -. traces, metrics, logs .-> O[Observability]
    B -. traces, metrics, logs .-> O
    C -. traces, metrics, logs .-> O

The integration boundary can be a direct network endpoint, API gateway, message broker, adapter, or workflow engine. Selecting it is an architecture decision, not a keyword-matching exercise.

Consider a checkout service that needs payment authorization. A synchronous request is useful because the caller needs an immediate decision. After the order is accepted, fulfillment and notification may be events because checkout does not need to wait for every downstream task. A webhook can later report a shipping status to a partner.

One business operation can therefore use several integration patterns.

Synchronous Request-Response Integration

In synchronous integration, the caller waits for a response. HTTP/REST and gRPC are common choices.

Use synchronous calls when:

• the caller needs an immediate answer;
• the downstream result determines the current response;
• the interaction can complete within a bounded deadline;
• both sides can tolerate temporal coupling.

A direct call is not inherently an anti-pattern. It makes the dependency visible and can be the simplest design for an internal service with one clear owner. Problems arise when dependency chains become long, failure behavior is undefined, or every caller reimplements discovery, authentication, and telemetry differently.

Example: Service-to-Service HTTP Call

POST /v1/authorizations HTTP/1.1
Host: payments.internal.example
Authorization: Bearer <workload-access-token>
Idempotency-Key: 780a7ab3-d6b6-49cb-979c-86347f3f01e2
Content-Type: application/json

{
  "order_id": "ord_8421",
  "amount_minor": 2599,
  "currency": "USD"
}

The example uses integer minor units to avoid binary floating-point ambiguity for money. The access token represents a workload identity and should have the intended issuer, audience, expiry, and permission. The idempotency key lets the receiving system recognize a repeated attempt; the exact behavior and retention window must be defined by the API contract.

Control the Dependency Chain

Every synchronous hop consumes part of the caller's deadline. If service A calls B, which calls C, which calls D, a slow or failing dependency can propagate latency and resource pressure upstream.

Set an end-to-end deadline, then allocate smaller downstream timeouts. Bound connection and request timeouts. Avoid a retry at every layer, because nested retries can multiply traffic. Use a circuit breaker only when it helps callers stop repeated work against an unhealthy dependency; it does not repair that dependency.

Asynchronous Events and Queues

In asynchronous integration, the producer records or publishes a message and does not wait for every consumer to complete. A broker or queue decouples the producer from consumer availability.

Use this pattern when:

• work can complete later;
• multiple consumers need the same event;
• traffic needs buffering;
• a durable workflow spans minutes, hours, or days;
• the producer should not fail merely because one consumer is temporarily unavailable.

sequenceDiagram
    participant O as Order Service
    participant B as Broker
    participant F as Fulfillment
    participant N as Notification
    O->>B: OrderAccepted event
    B-->>O: Publish acknowledged
    B->>F: Deliver event
    B->>N: Deliver event
    F-->>B: Acknowledge after durable handling
    N-->>B: Acknowledge after durable handling

Asynchronous does not mean failure-free. Delivery may be at least once, so consumers should be idempotent. Define message keys, ordering expectations, schema evolution, retention, retry, and dead-letter handling. Acknowledging a message before the outcome is durable can lose work; retrying forever can trap a poison message and exhaust resources.

For database changes followed by event publication, consider an outbox pattern so the business update and the record of the event are committed together. A separate publisher can send the outbox record and mark it delivered. Consumers must still handle duplicates.

Webhook Integration

A webhook lets a provider call a consumer-owned HTTP endpoint when an event occurs. It is useful for cross-organization notifications where the consumer cannot subscribe directly to the provider's internal broker.

Secure webhook processing by:

• using TLS and verifying the provider's signature or authentication mechanism;
• validating a timestamp and limiting replay windows;
• preserving the raw request bytes when the signature scheme requires them;
• acknowledging only after the event is durably recorded;
• processing slow work asynchronously;
• deduplicating on a stable event identifier;
• allowing safe key rotation.

Return a documented success code promptly after durable acceptance. A provider retry should not create a duplicate invoice, shipment, or account update.

Polling and Change Feeds

Polling is sometimes appropriate when the provider cannot push events or the consumer controls the schedule. Use conditional requests, cursors, or a change feed to avoid repeatedly downloading the entire dataset.

Polling creates a trade-off between freshness and load. A shorter interval detects changes sooner but creates more calls. Add jitter so many consumers do not poll at the same instant. Store a durable cursor and define how the consumer recovers if the cursor expires or a page is processed twice.

Batch and File-Based Integration

Not every integration needs a real-time API. Large, periodic datasets may be cheaper and easier to reconcile through an object store, managed file transfer, or batch export. Use a manifest, checksum, encryption, schema version, and completion marker so consumers can distinguish a complete file from a partial upload.

Batch integration can provide high throughput and a clear audit trail. It is unsuitable when the business process requires an immediate response.

API Aggregation and Backend-for-Frontend

A user interface may need information from several services. Making every mobile or browser client understand the service topology can create extra round trips and duplicate composition logic. A backend-for-frontend (BFF) or aggregation service can expose a consumer-specific endpoint and call the required services.

flowchart LR
    C[Mobile client] --> G[API gateway]
    G --> B[Dashboard BFF]
    B --> U[Profile service]
    B --> O[Order service]
    B --> S[Shipping service]

The gateway authenticates, applies traffic policy, and routes the request. The BFF owns the response composition, partial-failure behavior, caching, and business-specific data transformation.

This separation is important. Some gateways can call functions, run plugins, or perform limited transformations, but that does not make every gateway a general response-composition engine. Keep complex application logic in testable application code unless the gateway has a documented, supported capability that fits the requirement.

API Orchestration and Durable Workflows

Orchestration coordinates several steps to reach a business outcome. A short synchronous composition can live in an application service. A durable process with waits, compensation, human approval, or long-running state usually belongs in a workflow engine.

For an order workflow:

1. reserve inventory;
2. authorize payment;
3. create fulfillment work;
4. compensate a completed step if a later step fails, according to business rules;
5. record the outcome for audit and recovery.

The coordinator needs durable state and a defined recovery model. A timeout does not prove that a remote operation failed; it may have completed while the response was lost. Query by an idempotency key or operation identifier before blindly repeating a side effect.

An API gateway should not silently become the owner of this workflow. Gateways are designed to proxy and govern traffic. Business state, compensation, and long-running recovery should remain in a component that can persist and test them explicitly.

Where an API Gateway Fits

An API gateway is most valuable at an API entry boundary. It can provide:

• routing and service abstraction;
• TLS termination and client authentication;
• token validation and coarse-grained access policy;
• rate limiting and request-size controls;
• limited request or response transformation;
• canary routing and upstream load balancing;
• consistent metrics, logs, and traces.

For north-south traffic, this centralizes policies that would otherwise be repeated by every public API. For east-west service traffic, teams may use direct calls, a service mesh, internal gateways, or a combination based on trust boundaries and operating requirements.

Apache APISIX supports routing, upstream load balancing, authentication, traffic controls, and observability through its core and plugin system. It should be evaluated for those documented gateway functions. Custom plugins can extend behavior, but custom code creates its own maintenance and security responsibility.

Authentication and Authorization Between APIs

Machine-to-machine calls need workload identity. Common approaches include:

• OAuth 2.0 client credentials with narrowly scoped access tokens;
• mutual TLS with certificates tied to service identity;
• cloud-native workload identity;
• signed requests for a specific provider protocol;
• API keys for identification where their security properties are sufficient.

Validate tokens rather than merely decoding them. Check the expected issuer and audience, signature, time constraints, and required permissions. Rotate credentials and certificates safely. Do not place secrets in source code, URLs, or ordinary logs.

Authorization belongs at more than one layer. A gateway may reject a caller that lacks a required role or scope, while the service enforces whether that caller can access a specific order, account, or tenant. The gateway normally lacks the full business context for object-level decisions.

Failure Handling, Retries, and Idempotency

Classify failures before selecting a response:

Idempotency means repeating the same logical operation has the documented effect. It may be inherent for a PUT that replaces a known resource, or implemented with a unique operation key and stored result. It is not achieved by adding a random header if the server ignores it.

Use exponential backoff with jitter for distributed retries. Limit attempts and total time. A queue also needs bounded retries, visibility or lease semantics, and a plan for messages that can never succeed.

Data Contracts and Versioning

API integration fails when the transport works but the parties disagree about meaning. Define contracts for field semantics, units, time zones, identifiers, nullability, ordering, and error behavior.

Use additive changes where possible. A tolerant consumer can ignore an unknown optional field, but it cannot safely interpret an existing field whose meaning changed. Validate important assumptions at the receiving boundary and reject malformed data before it reaches business logic.

For events, treat the schema as immutable history. Introduce compatible versions and keep enough metadata to replay or audit old messages. For HTTP APIs, publish deprecation and migration guidance and inventory the consumers before retiring a version.

Observability for API Integrations

An integration needs a traceable operation identity across services and asynchronous boundaries. Collect:

• request or event rate;
• success and error outcomes;
• latency distributions;
• timeout, retry, and duplicate counts;
• queue depth and oldest-message age;
• webhook delivery attempts;
• dependency saturation;
• business completion signals.

Use distributed tracing where it adds diagnostic value, but do not put secrets or raw personal data into spans. Propagate trace context only across trusted boundaries and follow the applicable specification. Logs should identify the operation without recording bearer tokens, API keys, or sensitive payloads.

Choosing an API Integration Pattern

These patterns can coexist. Choose per interaction rather than declaring one platform the integration layer for everything.

Implementation Checklist

• Name the owning teams and the business outcome.
• Document the contract and versioning policy.
• Choose synchronous, asynchronous, webhook, polling, batch, or workflow behavior deliberately.
• Authenticate workloads and authorize operations at the correct layer.
• Define deadlines, retryable failures, backoff, and idempotency.
• Test duplicate, delayed, reordered, malformed, and unauthorized inputs.
• Make the success outcome and failure state observable.
• Define how credentials, schemas, and endpoints rotate.
• Exercise recovery before production traffic depends on it.

Conclusion

API-to-API integration is the design of a dependable boundary between independently owned systems. The important work is not merely sending an HTTP request. It is choosing the right communication pattern, preserving contract meaning, protecting identity and data, and recovering from partial failure.

An API gateway such as Apache APISIX can provide a consistent entry point for routing, security, traffic management, and observability. Direct calls, brokers, BFFs, adapters, and workflow engines solve other parts of the problem. A resilient architecture gives each component the responsibility it can perform and keeps business state out of infrastructure that was not designed to own it.