Skip to content

Web

API Integration Best Practices for Business Systems

Integrations break at the edges: timeouts, duplicates and changed fields. Learn the practices that keep connections between systems reliable.

By the CodeElectron engineering teamUpdated 7 min read
Illustration of two systems connected by API arrows with a retry loop, a webhook and a security key

Key takeaways

  • An integration is a promise that two systems will stay in sync even when networks fail, data changes and vendors update their APIs.
  • Design for failure: set timeouts, retry with backoff, use idempotency to avoid duplicates and queue work you can do later.
  • Secure every connection: keep keys out of code, verify webhooks, limit permissions and respect rate limits.
  • Log enough to trace every message, test in a sandbox with realistic data and plan for versioning and change.

What can go wrong

Connecting a shop to a payment provider, a POS to accounting software or an app to a courier looks simple on a diagram. In reality networks drop, services slow down, requests arrive twice, fields change names and vendors release new versions. An integration that ignores these facts works in the demo and fails on a busy Friday. The practices below do not remove failures; they make sure failures are expected, contained and recoverable.

Design principles

  1. 1Define the data contract first: which fields move, in which direction, how often and which system is the source of truth.
  2. 2Set timeouts on every call. A hanging request must not hang your whole application.
  3. 3Retry safely: use limited retries with increasing delays, and only for errors that may succeed later.
  4. 4Make operations idempotent: sending the same request twice must not create two orders or two charges. Use idempotency keys where the API supports them.
  5. 5Queue work that does not need an instant answer, so spikes and outages do not lose data.
  6. 6Handle partial failure: decide what happens if step two of three fails and make the state recoverable.
  7. 7Validate and map data at the boundary instead of trusting the other system’s format.
  8. 8Document the integration: what it does, where it runs and how to restart it.

Polling or webhooks

ApproachHow it worksGood forWatch out for
PollingYou ask the other system for updates on a scheduleSimple needs and systems without webhooksDelays, wasted calls and rate limits
WebhooksThe other system calls you when something changesNear real-time updatesVerifying the sender, duplicate deliveries and missed events
BothWebhooks for speed, polling as a safety netBusiness-critical flowsMore to maintain

Security

  • Store keys and tokens in a secrets manager or protected environment variables, never in code or chat.
  • Give each integration only the permissions it needs.
  • Verify webhook signatures and reject requests that fail verification.
  • Use HTTPS only, and rotate keys when people or vendors change.
  • Respect rate limits and back off when asked to slow down.
  • Avoid logging sensitive data such as full card numbers or personal details.

Our web app security checklist covers wider protections for the systems at both ends.

Observability and change

  • Log each request and response identifier so you can trace an order through every system.
  • Alert on failures and growing queues, not only on complete outages.
  • Keep a way to replay failed messages after you fix the cause.
  • Pin to a version of the other API and read the vendor’s change notices. Plan an upgrade rather than being surprised by one.
  • Test in the vendor’s sandbox with realistic data, including errors, timeouts and duplicates.

A worked example

A retailer connects its online shop to a courier service. In testing everything works, but in production a slow response causes the shop to retry and the courier creates two shipments for one order. The team adds an idempotency reference for each shipment, sets timeouts, queues requests and logs every call with the order number. A daily check lists orders without a courier reference, so problems are noticed within hours. This is an illustrative scenario, not a client story, but duplicate creation after a retry is one of the most common integration faults.

Questions to ask before building

  • Which system owns each piece of data, and what happens if they disagree?
  • What is the expected volume now and in a year?
  • What happens when the other service is down for an hour?
  • Who is notified when an integration fails, and who fixes it?
  • Who owns the credentials, and how are they rotated?

Next step

Plan integrations as part of a larger system with our ERP implementation plan, see how bots connect to systems in chatbots for customer support, explore web development, or contact us about integrating your systems.

Frequently asked questions

What is idempotency in an API integration?

It means that repeating the same request has the same effect as sending it once. It prevents duplicates, such as two orders or two charges, when a request is retried after a timeout.

Should I use webhooks or polling?

Webhooks give faster updates but need verification and handling of duplicates and missed events. Polling is simpler but slower. Critical flows often use webhooks with polling as a safety net.

How do I test an integration safely?

Use the vendor’s sandbox with realistic data, and test failures too: timeouts, duplicate messages, invalid data and rate limits. Then roll out gradually and monitor closely.

Have a question we have not covered?

Ask the team directly. We are happy to talk through your situation.