4 November 202612 min read

API Integration Best Practices: A Practical Guide

A 1980s telephone exchange patch panel with three patch cords connecting jack fields, a brass key tag and clipboard on the shelf below, and one small amber indicator lamp lit.

A good API integration comes down to six habits: decide which system owns each piece of data, pick the pattern that fits the job, secure every connection, assume calls will fail, monitor business outcomes instead of server status, and write down how it all works. The rest of this guide shows how to apply each habit, including what changes when one of the systems is an ERP and the data is subject to Swiss rules.

TL;DR

Name one system of record for every data object (customer, invoice, stock level) before you write any code.
Match the pattern to the job: request-response for real-time lookups, webhooks for events, batch for volume and schedules.
Treat failure as normal: use idempotency keys, retries with backoff, and a queue you can inspect.
Secure with least-privilege access, stored secrets and an API gateway; in Switzerland, personal data also brings legal duties.
Monitor outcomes (orders that never reached the ERP), not just uptime, and document the integration for whoever maintains it next.

What API integration means in practice

An API (application programming interface) lets one piece of software talk to another in a standardized way, so data moves automatically instead of being retyped. Swiss Innovation Hub describes it as removing data silos and manual entry. For a business, that usually means a web shop that pushes orders into the ERP, a CRM that receives new leads from a form, or an accounting tool that receives invoices without a person in between.

The code that makes the call is the small part. Most integrations that go wrong fail because of unclear decisions made earlier: who owns the data, what happens when a record is rejected, who gets told. The practices below follow the order in which those decisions come up.

Start with requirements, not endpoints

Before reading any documentation, write down in plain language what should happen. A useful requirements note answers five questions:

Which event starts the flow? A paid order, a new contact, a changed price.
Which fields travel, and in which direction? One-way or two-way sync are very different projects.
Which system is the source of truth for each field? If both can edit a customer’s address, you have already designed a conflict.
How fast must data arrive? Seconds, minutes, or overnight.
What happens on failure, and who is told?

The usual planning sequence is to define requirements, read the provider’s documentation, build and test in a sandbox, design error handling, and document the result, as outlined by Merge. Skipping the first step is the most common reason projects are rebuilt halfway through.

Read the provider’s limits early

Check rate limits, pagination, authentication methods, versioning policy and sandbox availability before you commit to a design. A system that allows 60 calls a minute cannot be fed by a design that fires one call per product line during a 20,000-item import. Finding that out in week one costs an afternoon; finding it out at launch costs a redesign.

Choose the right integration pattern

Three patterns cover most business needs, as Gusto’s developer guide summarizes: synchronous request-response, event-driven webhooks and batch processing.

Pattern	How it works	Use it when	Watch out for
Request-response	Your system calls the API and waits for the answer	You need a result now: price lookup, address validation, payment authorization	The user waits if the other system is slow or down
Webhook (event-driven)	The other system calls you when something happens	You react to changes: order paid, ticket closed, subscription cancelled	Events can arrive twice, late or out of order
Batch	A scheduled job moves many records at once	Large volumes or non-urgent data: nightly stock, monthly reporting exports	Data is stale between runs; one bad record can stall a whole file

Most real integrations mix them. A shop might check stock with a live request at checkout, receive shipping updates through webhooks and reconcile accounting data in a nightly batch.

Orchestration or choreography

When several systems take part in one process, you have two ways to coordinate. In orchestration, one central component calls each step in order and decides what to do on failure. In choreography, each system reacts to events and does its own part. Gusto’s developers suggest orchestration for complex, dependent workflows and choreography for parallel, independent tasks. For a small team, orchestration is usually easier to reason about and debug, because the whole flow lives in one place. Choose choreography when steps truly do not depend on each other.

Design for failure from day one

Networks drop, providers deploy bugs and queues back up. An integration that only works when everything works is a demo. Four techniques make the difference.

Idempotency

If a request is retried, it must not create a second invoice or charge a customer twice. HTTP defines some methods as idempotent, meaning repeated identical requests have the same effect as one; RFC 9110 sets this out. Creating records is typically a POST, which is not idempotent by default, so important write operations should carry a unique request identifier (an idempotency key) that the receiving system uses to recognize and ignore duplicates. Generate the key once per business action, not once per attempt.

Retries with backoff

Retry temporary errors (timeouts, 429 and 5xx responses), but wait longer after each failure and add a little randomness so many clients do not retry at the same instant. Do not retry errors that will never succeed, such as a rejected field or a missing permission. Those belong in a review queue.

Circuit breakers and queues

If a downstream system is down, stop hammering it. A circuit breaker pauses calls after repeated failures and tests again later. Put outgoing work on a queue so a one-hour outage at the provider means a delay, not lost orders.

Validate at the boundary

Check incoming data before it reaches your core system: required fields, formats, lengths, allowed values. Reject or quarantine bad records with a clear reason, and never let one malformed row break a whole batch.

Secure every connection

An integration is a standing door between two systems, often holding broad permissions. Treat it like a user account with a very long life.

Use proper authentication. Prefer OAuth 2.0 where the provider supports it; otherwise use API keys that you can rotate.
Grant least privilege. If the integration only reads orders, it should not be able to delete customers.
Store secrets safely. Keep keys in a secrets manager or encrypted environment configuration, never in source code, tickets or chat.
Rate-limit and log. Record who called what, with a correlation ID that follows a request across systems, so you can trace a problem end to end.
Put a gateway in front. The Swiss Federal Chancellery’s API architecture for the federal administration recommends an API gateway between clients and backend services to mediate communication and control access, and it requires identity and access management for partner and registered public APIs. The same logic applies to a private company exposing endpoints to partners.

For a concrete list of what attackers target in APIs, such as broken object-level authorization, the OWASP API Security Top 10 is the reference security teams use. If you also need to prove your controls to auditors or customers, a compliance platform such as Guardiso’s security and compliance tools can help you manage access control and credential-handling evidence alongside standards like ISO 27001.

Swiss data protection duties

If an integration moves personal data, such as customer names, addresses or order history, Swiss law applies. Under the Data Protection Ordinance (SR 235.11), controllers and processors must adopt technical and organizational measures appropriate to the risk, to protect confidentiality, availability, integrity and traceability. For automated processing this includes access control so authorized persons reach only the data they need, and handling of malfunctions with the ability to restore quickly. In practice that maps directly onto least privilege, audit logs and the failure handling above. For your specific case, such as data sent to a provider abroad, ask your data protection adviser or legal counsel.

Monitor outcomes, not just servers

A green status page does not prove data is flowing. An integration can be “up” while every third order is rejected because a field changed. Track both layers:

Technical: error rates, latency, retry counts, queue depth, authentication failures.
Business: approved orders that never reached the ERP, missing shipment tracking numbers, unmatched products, stock discrepancies and transactions waiting in a queue, the kinds of checks Midrocket’s integration guide lists.

Send alerts to a person with a clear owner, not to a shared inbox nobody reads. Add a daily or weekly reconciliation that compares counts between systems (orders in the shop versus orders in the ERP). It catches the failures no alert was written for.

Document and version the contract

Write down what the integration sends, receives, assumes and does on error. Include field mappings, authentication setup, retry rules, the owner of each system and a runbook for the three most likely failures. Documentation lets another engineer troubleshoot at 8 a.m. on a Monday without calling the person who built it.

Version your own interfaces too. When you change a field, add a new version and give consumers time to move, instead of breaking them overnight. And track the provider’s deprecation notices: most outages after launch are not bugs but a provider quietly retiring an old version.

ERP integration: where projects usually stumble

ERP integration follows the same practices, but the stakes are higher because the ERP holds financial records. The recurring problems are consistent:

Unclear ownership of shared data. Customer, product and price data often live in three places, and nobody decided which wins.
Weak data mapping. Different formats for names, units, tax codes and cost centers produce duplicates and misposted entries. In Swiss setups, hard-coded VAT rates and inconsistent customer names are classic causes.
No failure and duplicate controls. Without idempotency, a retry can post an invoice twice.
Poor visibility. Delayed or rejected transactions sit unnoticed until month-end close.
No plan for change. Either side upgrades and the integration silently breaks.

SAP notes that manually managing APIs as applications multiply creates complex, hard-to-maintain code, and that modern cloud ERP systems offer pre-configured connectors and integration platforms (iPaaS) for more scalable, secure connectivity. Where a ready-made connector exists and covers your case, use it; custom code is for what connectors cannot do.

How to avoid them

Map the workflow and the owner of each object before choosing tools.
Keep integration logic outside the ERP. Put transformations in a separate layer so an ERP upgrade does not mean rewriting business rules, and so you can swap a connected system without touching the ERP.
Validate with real data before automating. Run a first batch of real invoices or orders through the flow and have someone in finance check each one against the source. Stop-and-check beats cleaning up hundreds of wrong postings.
Add failure controls: idempotency, a dead-letter queue for rejected records, and clear error messages that finance staff can read.
Monitor business outcomes as described above.

Swiss standards to know

Some Swiss integrations are shaped by official standards. The eBilanz standard from Swissdec uses the XBRL-CH taxonomy and the eCH-0276 format for electronic transmission of companies’ annual accounts to tax authorities. Swissdec also published new major versions of its standards on 6 March 2026 (ELM 6.0, KLE 2.0, EO-Standard 1.0 and eBilanz 1.0), with guidelines valid from 1 April 2026. If your payroll or accounting software talks to these channels, check with your software vendor which version it certifies and plan the upgrade rather than discovering it at year-end.

A pre-launch checklist

Use this list before any integration goes live.

Area	Question to answer
Ownership	Is there one system of record per data object, and is it written down?
Pattern	Does the pattern (live call, webhook, batch) match how fast the data is really needed?
Limits	Are rate limits, pagination and version policy of every API accounted for?
Security	Are permissions minimal, secrets stored safely, keys rotatable and calls logged?
Data protection	Do you know which personal data moves, where it goes and who is responsible?
Failure	Are retries safe (idempotency), and do rejected records land somewhere visible?
Monitoring	Do alerts cover business outcomes, with a named owner?
Testing	Was it tested in a sandbox and with a small batch of real data?
Documentation	Could another engineer fix it without asking its author?
Change	Who watches provider deprecation notices and ERP upgrade schedules?

When to bring in help

A single connection between two well-documented tools is a reasonable in-house task. Help pays off when the integration touches an ERP or financial data, when several systems share the same records, or when the old system has no usable API and needs migration first.

At Ampersand, senior engineers stay on a project from the first conversation to handover, so the person who understands your requirements is the person who builds and documents the integration. We work on system integrations and API connectivity for shops, CRM and ERP, as well as migrations of legacy systems and ongoing support. Our pricing page lists the options, including single connections and integration suites. Our Run & monitor plan for ongoing monitoring is CHF 750 per month, and our Guidance advisory plan is CHF 799 per month. If you are unsure which pattern or setup suits you, start there.

FAQ

What are the most important API integration best practices?

Decide which system owns each piece of data, choose a pattern that fits the timing needs, and secure access with least privilege. Then make writes safe to retry with idempotency keys, monitor business outcomes, and document the integration. These cover most of the failures seen after launch.

Which API integration pattern should I use?

Use request-response when a person or process needs an answer immediately. Use webhooks when you want to react to events without polling, and batch for large or scheduled transfers where a delay is acceptable. Most business integrations combine two or three.

What are the biggest ERP integration challenges?

Unclear data ownership, weak field mapping, missing duplicate and failure controls, and poor visibility into rejected transactions cause most problems. Lack of a plan for application or API changes comes next. Settling ownership and mapping before building prevents most of them.

Do Swiss data protection rules apply to API integrations?

Yes, when an integration processes personal data. The Data Protection Ordinance requires technical and organizational measures appropriate to the risk, covering confidentiality, availability, integrity and traceability. Your data protection adviser can confirm what applies to your data flows.

How do I know an integration is working after launch?

Track business outcomes, such as orders that failed to reach the ERP or stock levels that differ between systems, alongside technical metrics. A scheduled reconciliation between the two systems catches problems that alerts miss.

Sources

Talk to us

Have a project this touches on?

A free 10-minute call is the fastest way to find out whether we are the right studio for it.

Book a free 10-min call

Keep reading