API Architecture: How to End Integration Hell in Your Business

Integration hell is the operational state where systems that should communicate with each other do so — but through a mesh of point-to-point connections, undocumented data transformations, and brittle handoffs that break regularly and require individual attention to fix.

Its typical symptoms in a Nigerian business:

Accounting and inventory systems are "integrated" through a scheduled export file that sometimes fails silently
Customer records exist in three systems with different formats and the systems periodically contradict each other
A new integration request takes 6–12 weeks because it requires modifying code in multiple systems written by different teams over different years
When a system is upgraded or changed, two other integrations break in ways nobody anticipated

Integration hell is not fixed by choosing a better integration tool. It is fixed by introducing architecture discipline — a set of principles for how systems share data, backed by technical patterns that implement those principles consistently.

The Root Cause of Integration Mess

Point-to-point integrations made sense when they were built. System A needed data from System B. A developer wrote code to call System B's API (or export data to a file) and import it into System A. Solved.

The problem surfaces at the fourth integration. System A, B, C, and D are now individually connected to each other through a spider web of integrations. When System B's API changes, three integrations break. When a new System E joins, it needs to integrate with each of the others — four new integration points, each slightly different because they were built at different times by different people.

The integration count grows as $n(n-1)/2$ where n is the number of systems. With 8 systems, that is 28 potential direct integrations. With 12 systems: 66.

The architectural solution: hub-and-spoke integration through a central layer (API gateway or integration bus) rather than mesh integration direct system to system.

The API Contract Model

The first principle of integration discipline: every integration must go through a published, versioned API contract. A contract specifies:

The endpoint (URL pattern and HTTP method)
The request format (body schema, required and optional fields, types)
The response format (success and error cases)
Authentication mechanism
Rate limits
Versioning policy

Undocumented integrations are not integrations — they are undeclared dependencies. When System B's response format changes, the integration breaks silently unless there is a contract that both parties know about and that explicitly handles versioning.

OpenAPI Specification (formerly Swagger): The industry standard for documenting REST APIs. An OpenAPI file describes every endpoint, its parameters, its request body, its response schemas, and authentication. Client code can be generated from it. Documentation can be generated from it. Tests can be generated from it. If you do not have OpenAPI documentation for your internal APIs, start there.

REST vs GraphQL: When Each Is Appropriate

REST (Representational State Transfer)

REST APIs use HTTP methods (GET, POST, PUT, PATCH, DELETE) with resource-based URLs. Each endpoint returns a defined resource or collection. Widely supported by every language, framework, and tool.

Best for:

Public APIs where diverse clients consume the same endpoints
Systems integration where the consumer needs complete, well-defined resources
CRUD operations where the resource structure is stable
Internal integrations with clear, bounded resource types

GraphQL

GraphQL is a query language for APIs that allows clients to request exactly the data they need in a single query, rather than making multiple REST requests or over-fetching from endpoints that return more data than needed.

Best for:

Frontend applications with complex data requirements where different views need different subsets of the same data
Applications with highly variable data needs per request
APIs serving multiple client types with very different data needs (mobile app vs. web app vs. third-party integration)

Real-world caution: GraphQL is powerful but introduces complexity in caching (REST responses are easily cacheable by URL; GraphQL caching is more complex, though solutions exist — persisted queries, CDN-level caching with query hashing, and client-side caching via Apollo Client or urql), security (unbounded queries can produce expensive database loads), and tooling (N+1 query problems require dataloader patterns). For internal business integrations between backend systems, REST is almost always simpler and sufficient.

Webhooks

Webhooks are event-driven callbacks: System A notifies System B when something happens, rather than System B polling System A to check for changes.

When webhooks replace polling: An accounting system that needs to know when a payment is received should not poll the payment gateway every minute. The payment gateway sends a webhook to the accounting system when a payment succeeds. This is more timely, less resource-intensive, and eliminates the polling interval delay.

Reliability considerations for webhooks:

The receiving system must respond with HTTP 200 within the timeout window or the sender will retry
Webhook delivery is at-least-once — your system must handle duplicate webhook events (ensure idempotency: processing the same event twice produces the same result as processing it once)
Webhooks fail silently if the receiving endpoint is down. A webhook log with retry logic on the sender side is required for reliability.

The API Gateway Pattern

An API gateway is a single entry point for all API traffic — external and potentially internal. It handles:

Authentication and authorisation: Rather than each service implementing authentication separately, the gateway verifies JWT tokens, API keys, or OAuth credentials centrally. Services behind the gateway know that requests have been pre-authenticated.

Rate limiting: Protect backend services from excessive load from any single client.

Request routing: Route incoming requests to the correct backend service based on path prefix or hostname.

Logging and observability: Every request and response passes through the gateway, enabling centralised logging of all API traffic without instrumentation in each service.

Transformation: The gateway can modify request or response format — useful when legacy services speak an older API format that you want to normalise at the gateway level.

Options: AWS API Gateway (managed, serverless, integrates with Lambda), Kong (open source, self-hosted, extensive plugin ecosystem), Nginx (lightweight, configurable as a simple reverse proxy and gateway), Cloudflare Workers (for edge gateway logic).

For most Nigerian business applications, the API gateway pattern is applied at the boundary of the application — all external API calls go through a defined interface with authentication and rate limiting. Strict internal service-to-service organisation through a gateway adds operational complexity that is only justified at larger scale.

Working with Nigerian enterprise clients, we consistently find that the biggest integration pain point is not technical complexity — it is the variety of data formats across local banks, payment processors, and government portals. A well-designed API layer that normalises these differences saves months of downstream development. One client's integration with four Nigerian banks required four different date formats, three different currency representations, and two different character encodings — all for what was conceptually the same bulk payment operation. The gateway transformation layer absorbed all of that variation, and the application code behind it dealt with a single canonical format.

Event-Driven Integration

For asynchronous integration between systems — where System A should notify System B of an event without requiring an immediate response — an event-driven architecture using a message queue or event bus is the correct pattern.

Message queue: System A publishes a message (e.g., OrderPlaced event) to a queue. System B subscribes to the queue and processes messages independently. If System B is temporarily down, messages accumulate in the queue and are processed when it recovers.

Benefits for Nigerian business contexts:

Resilient to temporary system unavailability (generator outages, network instability)
Decouples system release timing — System A and System B can be deployed independently
Allows multiple consumers — if both the billing system and the inventory system need to respond to OrderPlaced, both can subscribe to the same event without modifying the publishing system

Options: RabbitMQ (open source, mature), AWS SQS (managed, scales automatically), Cloudflare Queues (serverless, integrates with Workers), Redis Pub/Sub (for lightweight, non-persistent messaging).

Integration Health Monitoring

Every integration should be monitored. The monitoring questions:

Is the integration operational?: A health check endpoint that tests the communication path end-to-end. Checked every 5 minutes by an uptime monitor; alerting if the health check fails.

Is the data correct?: A reconciliation check that compares record counts or summaries between systems to detect silent data discrepancies (the import that ran but imported 947 records when 1,000 were expected).

Is it timely?: For time-sensitive integrations, check that data is not stale. An integration that should refresh every hour but has not updated in 4 hours should alert.

Integration monitoring — treating integrations as first-class operational concerns with their own health metrics — is the difference between knowing an integration broke and discovering it broke after a week of silent data inconsistency.

Microservices vs Monolith for Nigerian Businesses — Choosing the right architecture for your scale
Database Choices for Nigerian Business Applications — Selecting the right database for your architecture
Integrating Paystack and Flutterwave Beyond Basic Checkout — API integration patterns for Nigerian payment systems