API Integration: The Definitive Guide to Styles, Patterns, Auth and Reliability

TL;DR

• API integration connects software systems through their APIs; the hard parts are authentication, failure handling and change management, not the first successful request.
• Pick the API style by interaction shape: REST for resource CRUD, GraphQL for client-shaped reads, gRPC for typed service-to-service calls, webhooks and event streams for “tell me when something happens”.
• Retries are only safe when the operation is idempotent. HTTP defines which methods are, and the IETF Idempotency-Key draft and Stripe’s API show how to make POST safe to repeat.
• The OWASP API Security Top 10 (2023) lists broken object level authorization first and “unsafe consumption of APIs” last, which is the risk every outbound integration carries.
• LLM APIs add token-based rate limits, streaming and provider-specific formats; teams usually integrate once through an OpenAI-compatible endpoint, often an AI gateway such as Bifrost, LiteLLM, Kong AI Gateway or Cloudflare AI Gateway.

API integration is the work of connecting two or more software systems through their application programming interfaces so that data and actions flow between them without a person in the middle. Payments, identity, CRM sync and, increasingly, calls to large language models all depend on it. The first request takes minutes; an integration that survives timeouts, rate limits, duplicates and version changes takes much longer. This guide covers API integration from the specifications up, including LLM and agent integrations.

What Is API Integration

API integration is the connection of software systems through their published interfaces so that one system can read data from, write data to, or trigger actions in another. It includes the contract, the authentication, the transport, error handling, and the mapping between each side’s data model.

The provider publishes the API and decides its contract, limits and versioning. The consumer builds the client and owns everything that happens when the provider is slow, down or rate limiting, which is where most of the engineering effort sits.

Three properties separate a demo from a production integration: correctness under retries (a timed-out request may or may not have been applied), bounded consumption (every provider enforces limits, and many charge per call or per token), and tolerance of change as providers add fields and ship new versions.

API Styles: REST, GraphQL, gRPC, Webhooks and Events

API styles differ in who initiates communication and how the contract is described. REST and GraphQL are request-response over HTTP, gRPC is typed remote procedure calls over HTTP/2, and webhooks and event streams push data to the consumer when something changes. Most real integrations combine at least two.

REST maps resources to URLs and uses HTTP’s methods and status codes, which is why the semantics of RFC 9110 matter so much in practice. GraphQL lets clients request exactly the data you need from a typed schema. In gRPC, a client can directly call a method on a server application on a different machine as if it were local,.

Webhooks invert the flow. GitHub describes them as a way to receive data as it happens, as opposed to polling an API, and tells integrators to subscribe to webhook events instead of polling the API.

The receiver carries the burden. Stripe warns that webhook endpoints might occasionally receive the same event more than once, and GitHub signs each delivery: GitHub uses an HMAC hex digest to compute the hash.

Event streams go further and decouple producers from consumers entirely. Apache Kafka’s documentation says event streaming is the practice of capturing data in real-time from event sources, then stores and routes those streams to subscribers.

API Integration Patterns: Point-to-Point, Gateway, iPaaS, ESB and Event Bus

An API integration pattern describes where integration logic lives. In point-to-point integration, each application calls each API directly. Mediated patterns (an API gateway, an iPaaS, an enterprise service bus or an event bus) move authentication, routing, transformation and policy into one shared layer.

Figure 1: With N callers and M systems, point-to-point integration grows toward N times M connections, while a mediation layer needs N plus M.

As Figure 1 shows, the cost of point-to-point integration is multiplication: every pair carries its own credentials, retries and mapping.

API gateways such as Kong, Apigee, AWS API Gateway and Apache APISIX sit in front of APIs and centralize authentication, routing and rate limiting for inbound traffic. iPaaS products package connectors and workflow builders; Azure Logic Apps advertises 1,400+ prebuilt connectors, and MuleSoft, Boomi, Workato and Zapier compete in the same space. Enterprise service buses predate both and implement the classic enterprise integration patterns; Apache Camel, for example, lets developers route, transform, filter, split, and aggregate with the Enterprise Integration Patterns catalog. This site’s guide to the service integration bus covers ESB architecture and its modern successors in depth. Event buses (Kafka, Amazon EventBridge, cloud pub/sub services) remove direct calls altogether.

Outbound traffic to LLM providers is a newer pattern again, with its own unit of control (tokens and dollars rather than requests). The distinction is covered in this site’s comparison of AI gateways and API gateways, and the LLM section below returns to it.

API Authentication: API Keys, OAuth 2.0 and 2.1, and mTLS

API authentication proves which client is calling. API keys are static shared secrets; OAuth 2.0 issues scoped, expiring access tokens, and OAuth 2.1 consolidates its security best practices; mutual TLS authenticates the client with an X.509 certificate during the TLS handshake. Production integrations often combine two.

API keys remain the default for many SaaS and LLM APIs; store them in a secrets manager and rotate them.

OAuth 2.0 (RFC 6749) defines the client credentials grant for machine-to-machine integrations and the authorization code grant for acting on behalf of a user.

Its security guidance now lives in RFC 9700, the OAuth 2.0 Security Best Current Practice (January 2025), which states that public clients MUST use PKCE, that clients SHOULD NOT use the implicit grant, and that access tokens SHOULD be audience-restricted to a specific resource server.

OAuth 2.1 is still an Internet-Draft (revision 16), but it folds those rules into one document: the authorization code grant requires the addition of the PKCE parameters, redirect URIs must be compared using exact string matching, and the Resource Owner Password Credentials grant is omitted from this specification. New integrations should follow 2.1 behavior even against 2.0 servers.

mTLS binds identity to a certificate, and RFC 8705 defines certificate-bound access and refresh tokens using mutual Transport Layer Security, so a stolen token is useless without the matching private key.

The same OAuth 2.1 profile governs remote tool servers for agents: the MCP specification says authorization servers MUST implement OAuth 2.1, as this site’s explainer on MCP authentication details.

Building Reliable API Integrations

Reliable API integration rests on five practices: make writes idempotent, retry only transient failures with exponential backoff and jitter, respect the provider’s rate limits and Retry-After headers, paginate every collection, and pin API versions. Each is defined in public specs or provider docs.

Idempotency Keys

HTTP defines a method as idempotent if the intended effect on the server of multiple identical requests with that method is the same as the effect for a single such request. GET, PUT and DELETE qualify; POST does not, and RFC 9110 says that a client SHOULD NOT automatically retry a request with a non-idempotent method unless it knows the semantics are safe.

The idempotency key fixes this for POST: the client sends a unique value per logical operation and reuses it on every retry. The IETF HTTPAPI working group’s Idempotency-Key header draft describes it as a way to make non-idempotent HTTP methods such as POST or PATCH fault-tolerant. Revision 07 expired as a draft in April 2026 without becoming an RFC, but its error semantics are widely copied: the resource SHOULD reply with an HTTP 409 status code if a retry arrives while the original is still processing, and with 422 if the same key is reused with a different payload.

Stripe is the reference implementation. Its API docs explain that with an idempotency key a client can safely repeat the request without risk of creating a second object, recommend V4 UUIDs, and note that idempotency keys are up to 255 characters long. Microsoft’s REST guidelines solve the same problem with different headers, telling services to support the Repeatability-Request-ID & Repeatability-First-Sent request headers when an action must be safe to retry.

Retries With Exponential Backoff and Jitter

Retry only failures that can succeed later (network errors, timeouts, 5xx and 429), wait longer after each attempt, randomize the wait so clients do not retry in lockstep, and cap the attempts.

Figure 2: Retries are only safe after two checks pass: the error is transient and repeating the request cannot apply it twice.

The cap matters more than it looks. Amazon’s Builders’ Library describes a five-layer call stack with three retries per layer where, when the database starts failing, the load on the database will increase 243x. Its rule of thumb matches Figure 2: APIs with side effects are not safe to retry unless they provide idempotency. Retry in one layer only, usually the outermost client or a gateway.

API Rate Limiting

Every public API meters consumption, and the integration has to read the signals. The 429 Too Many Requests status code comes from RFC 6585, and the Retry-After header tells the client how long the user agent ought to wait before making a follow-up request.

Published limits vary widely:

• GitHub gives authenticated users a personal rate limit of 5,000 requests per hour, plus secondary limits on concurrency. Its guidance is blunt: if Retry-After is present, you should not retry your request until after that many seconds has elapsed.
• Stripe allows 100 requests per second in live mode by default and tells integrators to add randomness to the backoff schedule to avoid a thundering herd effect.
• LLM providers limit tokens as well as requests. Anthropic’s limits are measured in requests per minute (RPM), input tokens per minute (ITPM) and output tokens per minute, enforced with a token bucket.

A client-side limiter plus a queue turns 429s into back-pressure. A deeper treatment of how AI gateways handle rate limiting for LLM apps covers the token-based case.

API Pagination

Google’s AIP-158 makes pagination mandatory from day one because it is a backwards-incompatible change to add pagination to an existing method, and it standardizes page_size, page_token and next_page_token. GitHub signals pages through standard Web Linking: when results are paginated, the response headers will include a link header with next, prev, first and last URLs. Prefer opaque cursors over page numbers.

API Versioning

Versioning lets a provider ship breaking changes without breaking consumers. Google puts the major version in the path and states that Google APIs use v1, not v1.0, v1.1, or v1.4.2. Microsoft’s guidelines instead use a required query parameter named api-version on every operation, with date-based values. Consumers should pin the version and ignore unknown response fields.

API Security and the OWASP API Security Top 10

The OWASP API Security Top 10 (2023 edition) is the standard checklist for API risk. Most items are provider-side authorization failures, but the last one targets integrators who trust third-party responses more than user input.

API4 now covers cost, the failure mode of an unbounded loop calling a paid LLM API, and API10 applies doubly to agents that act on whatever a tool returns. This site’s guide to MCP server security covers that case.

API Observability With OpenTelemetry

API observability means every integration call emits traces, metrics and logs that show latency, errors, retries and cost per dependency. OpenTelemetry is the vendor-neutral standard for producing that telemetry, so the same instrumentation works with Jaeger, Prometheus, Grafana, Datadog or any other backend.

OpenTelemetry describes itself as open source, as well as vendor- and tool-agnostic, and one of its stated principles is that you own the data that you generate. For integrations, the essentials are:

• A span per outbound call using the HTTP semantic conventions, with retries as separate attempts.
• Propagated trace context (W3C traceparent) across service boundaries.
• Provider request IDs in logs, such as the x-ms-request-id that Microsoft’s guidelines require.
• Metrics per dependency: error rate, latency percentiles and remaining rate-limit budget.

LLM calls need extra attributes (model, token counts, cost). OpenTelemetry’s GenAI semantic conventions have moved to the OpenTelemetry GenAI semantic conventions repository, and gateways increasingly emit them directly. This site’s roundup of LLM observability tools compares the backends.

API Specifications: OpenAPI and AsyncAPI

API specifications are machine-readable contracts. OpenAPI describes request-response HTTP APIs and AsyncAPI describes message-driven and event APIs. Both let teams generate clients, mock servers, tests and documentation from one source, which turns integration from reading prose into compiling against a contract.

The OpenAPI Specification defines a standard, language-agnostic interface to HTTP APIs that both humans and computers can read; the current release is version 3.2.1, dated September 2026. AsyncAPI exists to describe message-driven APIs in a machine-readable format across Kafka, AMQP, MQTT, WebSockets and HTTP, and is at version 3.1.0.

A practical rule: if a provider publishes an OpenAPI document, generate the client from it and run contract tests against the provider’s sandbox in CI. If it does not, write a minimal one for the endpoints you use.

Build vs Buy: API Integration Platforms and Tools

The build vs buy decision for API integration depends on how many integrations you need, who maintains them, and how differentiated they are. Building in code gives full control for a few core integrations; iPaaS products win when business teams need dozens of standard SaaS connectors.

Whatever is bought, the consumer still owns idempotency, data mapping and maintenance.

LLM API Integration: Provider Differences, Streaming, Failover and Cost

LLM API integration has every property of ordinary API integration plus four of its own: providers use different request formats, responses stream token by token, outages and 429s are frequent enough to need cross-provider failover, and cost scales with tokens rather than requests. Most teams handle these differences through an OpenAI-compatible endpoint.

Provider Differences and OpenAI-Compatible APIs

OpenAI, Anthropic, Google, AWS Bedrock and Azure each define their own message formats, tool-calling schemas, error codes and limits. Anthropic, for example, returns a 529 overloaded error and documents that 529 errors can occur when the API experiences high traffic across all users. The OpenAI request format has become the common denominator: Google states that Gemini models work with OpenAI libraries by updating three lines of code and using your Gemini API key.

Compatibility layers have limits. Anthropic describes its own OpenAI SDK layer as not considered a long-term or production-ready solution for most use cases, and newer interfaces such as the OpenAI Responses API move beyond the chat completions shape. A survey of LLM API providers and how to use them through one gateway maps the main differences.

Streaming

Both major providers stream over server-sent events. OpenAI’s guide explains how to stream model responses from the OpenAI API using server-sent events, and Anthropic notes that each server-sent event includes a named event type and associated JSON data. Streaming breaks ordinary assumptions: an error can arrive after a 200 status, a retry after the first token discards partial output, and proxies must not buffer the response.

Failover and Cost

Cross-provider failover is harder than retrying a replica because the fallback speaks a different API, and cost needs per-team attribution. Both are standard AI gateway features, the Figure 1 mediation layer for model traffic. Approaches teams use today include:

• Kong AI Gateway extends Kong’s API platform with plugins, whether serving LLM traffic, exposing structured context via MCP or coordinating agents through A2A; this site’s list of Kong alternatives compares it with dedicated gateways.
• Azure API Management adds an AI gateway to an existing APIM deployment; its unified model API (in preview) exposes multiple backends through a single OpenAI-compatible endpoint.
• Cloudflare AI Gateway is a hosted option that adds analytics, caching and rate limiting, and improves resilience by defining request retry and model fallbacks in case of an error.
• LiteLLM is a self-hosted Python proxy that gives applications one OpenAI-compatible endpoint for 100+ LLM providers, with virtual keys and spend tracking.

Broader comparisons are in this site’s ranking of top AI gateways and its guide to failover across Bedrock, Vertex and Azure.

Worked Example: Integrating LLM APIs Through Bifrost

Bifrost is an open-source AI gateway written in Go by Maxim AI. It is used here as the worked example because it is self-hostable and its public docs cover every reliability practice discussed above, from retries with backoff to OpenTelemetry export, so each claim below is checkable. It exposes 25+ providers and 10,000+ models through one OpenAI-compatible API, and Bifrost’s published benchmark reports 11 µs of added overhead per request at 5,000 RPS on an AWS t3.xlarge.

Figure 3: The application integrates once with an OpenAI-compatible endpoint; provider differences, failover and tool access are handled behind it.

Mapped to the practices in this guide:

• One contract. The gateway acts as a drop-in replacement for popular AI SDKs: existing OpenAI, Anthropic or Google GenAI clients change only their base URL. A walkthrough of using any LLM provider with the OpenAI SDK shows the change in each SDK.
• Retries the way Figure 2 describes. On transient failures, the docs state that it waits using exponential backoff with jitter before the next attempt, rotates keys on per-key failures such as 429s, and does not retry caller errors.
• Cross-provider failover. A request can list fallback models on other providers, and each fallback provider gets its own full retry budget. The pattern is explained further in an article on failover routing strategies for LLMs.
• Credentials and cost. Virtual keys are the primary governance entity in Bifrost, carrying per-key provider access, budgets and rate limits so provider secrets never reach applications. Semantic caching stores responses and can replay them for repeated requests, avoiding a round-trip to the provider. A guide to monitoring LLM API costs in production covers attribution by key and team.
• Observability. Its OTel plugin exports traces in which all traces follow OpenTelemetry semantic conventions, including the GenAI format.

A minimal client change looks like this:

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8080/openai",  # gateway instead of api.openai.com
    api_key="sk-bf-...",                      # virtual key, not a provider key
)

Deployment note. Bifrost runs as a single binary, a Docker container or a Kubernetes deployment inside your own network; clustering, guardrails, SSO and audit logs are part of the Enterprise tier. Provider-by-provider setup steps are in the Bifrost provider guides, and a buyer-side checklist is in the LLM gateway buyer’s guide.

Agents Calling APIs Through MCP

The Model Context Protocol (MCP) is the emerging standard for letting AI agents call APIs. An MCP server wraps an API as typed tools that a model lists and invokes over JSON-RPC, so every practice in this guide (authentication, rate limits, idempotency, input validation) applies to calls a model decides to make.

MCP changes who initiates the call, not what the call needs. The specification’s tools page asks clients to present confirmation prompts to the user for operations and asks servers to rate limit tool invocations. Three additions matter for agents:

• Least privilege per agent: expose only the tools its task needs.
• Tool output as untrusted input: OWASP API10 applies, since injected instructions can arrive inside an API response.
• Idempotency for agent retries: models repeat actions, so write tools need idempotency keys.

Gateways are taking on the MCP role as well. Bifrost’s MCP documentation states that by default, Bifrost does NOT automatically execute tool calls, and MCP tool filtering lets an administrator create a strict allow-list of MCP clients and tools per virtual key.

The essay on the MCP protocol, the plumbing and the gateway explains why tool traffic converges on one control point, and an article on MCP authentication with OAuth, API keys and token management covers the credential side. For agent-to-agent delegation, see this site’s comparison of A2A and MCP.

Choosing an API Integration Approach

API integration is a reliability and security discipline more than a connectivity one. The durable work is idempotent writes, disciplined retries, respect for rate limits, explicit versions and telemetry on every call, all specified in public RFCs and provider guidelines.

For a handful of core integrations, a generated client with those controls in code is usually the right call. As the count grows, a mediation layer earns its keep: an API gateway for inbound traffic, an iPaaS or event bus for business workflows, and, for LLM traffic, an AI gateway that adds token budgets and cross-provider failover. Among the AI gateways reviewed here, Bifrost covers the most of this guide’s practices in an open-source, self-hosted package; Kong and Azure API Management suit teams already on those platforms, Cloudflare AI Gateway suits teams wanting a hosted edge service, and LiteLLM suits Python-centric teams. Agents calling tools through MCP do not change the rules; they make skipping them more expensive.