API-Based Architecture: Integration Design for Customer Systems

Almost no FDE solution stands alone — it plugs into the customer's existing systems, and the plug is nearly always an API. This tutorial covers how API-based systems are structured, then the patterns for connecting your solution to everything else in the customer's world.

Table of Contents

• What Is an API?
• API-Based Architecture: The Shape
• Designing a Good API
• Synchronous vs. Asynchronous Communication
• What Is Integration Architecture?
• The Main Integration Patterns
• Choosing an Integration Pattern
• Handling Failure in Integrations
• Working Example: Connecting to the Customer's ERP
• Best Practices

What Is an API?

An API (Application Programming Interface) is a contract: one program exposes a set of operations, and other programs call them without knowing how they're implemented. In practice, "API" almost always means a web API — you send an HTTP request, you get a structured response back.

GET https://api.example.com/deliveries/4821

→ 200 OK
{
  "id": 4821,
  "status": "delivered",
  "driver": "M. Osei",
  "delivered_at": "2026-08-18T14:32:00Z"
}

APIs are the reason modern systems can be assembled instead of built as one block: each system owns its data and offers operations on it, and everyone else calls instead of reaching in.

API-Based Architecture: The Shape

An API-based architecture separates the system into layers that talk over HTTP:

[ Web app ]  [ Mobile app ]  [ Partner systems ]
      \           |              /
       ▼          ▼             ▼
      ┌────────────────────────────┐
      │           API              │   ← one contract, many consumers
      │  (auth, validation, logic) │
      └─────────────┬──────────────┘
                    ▼
             [ Database ]

The payoff: the API is the single front door. Add a mobile app, a dashboard, or a partner integration without touching the core logic — they all speak the same contract.

The two most common API styles:

GraphQL and gRPC exist too, but REST plus webhooks covers the large majority of FDE work.

Designing a Good API

Whether you're building an API or judging someone else's, the same qualities matter:

• Predictable URLs. Resources are nouns, organized consistently:

GET    /deliveries          → list deliveries
GET    /deliveries/4821     → one delivery
POST   /deliveries          → create
PATCH  /deliveries/4821     → update
DELETE /deliveries/4821     → remove

• Meaningful status codes. 200 OK, 201 created, 400 bad request, 401 not authenticated, 403 not allowed, 404 not found, 429 too many requests. Codes are part of the contract — don't return 200 for everything.
• Consistent error bodies. Errors should be machine-readable:

{
  "error": "validation_failed",
  "message": "status must be one of: pending, in_transit, delivered",
  "field": "status"
}

• Versioning. When the contract changes, old consumers must keep working. A URL prefix (/v1/deliveries) is the simplest approach.
• Pagination. List endpoints never return everything: GET /deliveries?page=2&limit=50.

Best Practice: design the API from the consumer's point of view. Write down the calls a dashboard or integration would want to make, then build endpoints to match. APIs designed from the database outward are awkward to use.

Synchronous vs. Asynchronous Communication

Every connection between two systems is one of two kinds:

• Synchronous — the caller waits for an answer. Request → response. Simple, immediate, but the caller is blocked and shares the callee's fate: if the other system is slow or down, you are too.
• Asynchronous — the caller drops a message and moves on; the receiver processes it later. Via queues, events, or webhooks. More moving parts, but the systems are decoupled — a slow receiver never blocks the sender.

Sync:   [Order service] ──"charge card?"──▶ [Payments] ──"yes/no"──▶ back
        (waits; fails if Payments is down)

Async:  [Order service] ──"order placed"──▶ [Queue] ──▶ [Email worker]
                                                    ──▶ [Analytics worker]
        (moves on; workers catch up when they can)

The rule of thumb: use sync when the caller needs the answer now (checking stock, validating a login); use async when the work can happen later (sending email, updating analytics, syncing to an ERP).

What Is Integration Architecture?

Integration architecture is the design of how your solution exchanges data with the customer's existing systems — ERPs, CRMs, accounting tools, legacy databases, spreadsheets with a prayer. In FDE work this is often most of the project: the new feature is easy; making it coexist with fifteen years of existing software is the job.

Every integration design answers four questions:

1. What data moves? Which fields, in which format, in which direction?
2. When does it move? Real-time, on a schedule, or on demand?
3. How does it move? API call, webhook, file drop, shared database?
4. What happens when it fails? Retry, alert, queue, roll back?

The Main Integration Patterns

Note: legacy systems dictate the pattern more often than preference does. If the customer's 2008-era ERP only exports CSV files to a folder at midnight, your integration is a nightly file job — and that's a legitimate architecture.

Choosing an Integration Pattern

Work through the questions in order:

1. Does the other system have an API?
   No  → file exchange or shared export; schedule it.
   Yes ↓
2. Do you need the data instantly?
   No  → scheduled sync is simpler and more robust. Done.
   Yes ↓
3. Who initiates?
   You need their events  → webhook (if supported)
   You need their data    → direct API call
   Many systems need it   → publish to a queue/event bus

Best Practice: when real-time and batch both satisfy the requirement, choose batch. A sync job that runs every 15 minutes is dramatically easier to build, debug, and explain than a real-time pipeline — and "within 15 minutes" is good enough for most business processes.

Handling Failure in Integrations

Integrations fail more than anything else you'll build, because they depend on systems you don't control. Design for it:

• Retries with backoff. Try again after 1s, then 2s, 4s, 8s… Most failures are temporary.

import time

def call_with_retry(fn, attempts=5):
    for i in range(attempts):
        try:
            return fn()
        except Exception:
            if i == attempts - 1:
                raise
            time.sleep(2 ** i)   # 1s, 2s, 4s, 8s

• Idempotency. Retries mean the same message can arrive twice. Design operations so doing them twice is harmless — e.g., key every record by an external ID and upsert instead of blindly inserting.
• Dead-letter handling. After N failed retries, don't drop the data — park it somewhere visible and alert a human.
• Timeouts. Every external call gets a timeout. A call that hangs forever is worse than one that fails fast.
• Monitoring. Track sync success rates and lag. "The ERP sync has been silently failing for three days" is a classic integration horror story; a single alert prevents it.

Working Example: Connecting to the Customer's ERP

Back to the delivery solution: every confirmed delivery must reach the customer's ERP for invoicing. Facts from discovery:

• The ERP has a REST API for creating invoice records.
• Invoicing runs once a day — real-time is not required.
• The ERP goes down for maintenance every Sunday night.

Applying the decision path: API exists ✓ → real-time not needed → scheduled sync.

[ Deliveries DB ]
       │
       ▼  every 15 minutes
[ Sync job ] ── reads undelivered-to-ERP confirmations
       │        (flag: erp_synced = false)
       ▼
[ ERP API: POST /invoice-records ]
       │
       ├── success → set erp_synced = true
       └── failure → retry with backoff; after 5 tries,
                     leave flag false + alert the team

Why this design holds up: the flag makes the job idempotent and resumable — rerunning it after an ERP outage just picks up the unsynced rows. Sunday maintenance causes a 15-minute delay, not data loss. And the whole integration is one small job that anyone can understand.

Best Practices

• Own the interface. Wrap every external system behind your own thin module. The rest of your code calls erp.create_invoice(...), never the vendor SDK directly — so the vendor stays swappable.
• Log both sides. For every integration call, log what you sent and what came back (with secrets redacted). Debugging without those logs is guesswork.
• Agree on the contract in writing. For any two-team integration, a one-page doc of fields, formats, and error behavior prevents weeks of back-and-forth.
• Start with the smallest working slice. One field synced end-to-end proves the path; then add fields.