Third-Party API Integration: What to Plan For
API integration connects your product to another service so they can exchange data or request actions. Before committing to a provider, plan how that connection should behave when requests are delayed, limits are reached or the outcome is unclear. Your build scope should also cover webhooks, version changes, production testing, running costs and a practical way to leave.
What should you decide before choosing an API?
Start with the business action, not the provider's feature list. Describe what the customer needs to accomplish and which part depends on the outside service.
For a delivery integration, that might mean requesting a shipment, receiving its tracking details and displaying its progress. Treat those as separate steps with separate failure states.
Ask your build partner to document:
- What data leaves your product and why.
- Which actions need an immediate answer.
- Which work can wait in a queue.
- What customers see while an action is pending.
- Who resolves an action that cannot finish automatically.
Choose the API style after clarifying that workflow. Our guide to REST vs GraphQL explains the interface choices; the integration plan should explain the customer experience around them.
How should you plan for rate limits?
Ask the provider which limits apply to your intended account and operations. Verify whether allowances are shared across customers, credentials or individual actions. Record how your application should detect a limit and when it may resume.
Then compare those rules with your busiest expected workflow, including background work.
Illustrative example: importing 300 records through an endpoint that accepts one record per request requires 300 initial requests. With an assumed allowance of 60 requests per minute, budget at least five minutes of capacity before allowing for other traffic or retries. These are planning assumptions, not a provider's published limits.
Decide whether users should wait, receive a progress message or return later. Give interactive requests priority where appropriate, and put a ceiling on queued work so a backlog remains manageable.
What should happen when a request fails?
Define the next action for each failure category before implementation.
| Situation | Planned response | Customer experience |
|---|---|---|
| Invalid input | Correct the input before resubmitting | Explain what needs changing |
| Access denied | Investigate permissions or credentials | Explain that the connection needs attention |
| Request allowance reached | Pause according to the provider's documented rules | Show that work is waiting |
| Temporary service failure | Retry eligible actions within a defined budget | Keep a clear pending state |
| Timeout with an unknown outcome | Check whether the action completed before repeating it | Avoid claiming success or failure prematurely |
The difficult case is uncertainty. Design for the possibility that your request reaches the provider but its response never reaches your application.
For actions with consequences, ask whether the provider supports an idempotency key: a request identifier with documented rules for recognising repeated submissions. Verify its scope and retention period rather than assuming that supplying a key makes every retry safe.
Where that protection is unavailable, require a way to look up the original action or route it for review. Set retry limits, waiting intervals and an escalation path. “Retry until it works” is not an acceptance criterion.
How should webhooks fit into the workflow?
A webhook lets another service notify an endpoint in your application about an event. Decide which events matter, how to authenticate them and what each should change.
Ask the provider to document delivery attempts, ordering and recovery options. Unless its contract gives stronger guarantees, design your handler to tolerate duplicate notifications, delayed notifications and events arriving in an unexpected order.
Separate receiving an event from completing the business work. Define when the event is safely recorded, when to acknowledge it under the provider's rules, and how failed processing will be recovered.
Include a reconciliation path: a way to compare your records with the provider's records and investigate differences. For example, support staff should be able to check a shipment whose status has remained pending, without asking the customer to create it again.
What should you verify about access and data?
Specify the permissions the integration actually needs. Ask for the narrowest suitable access, and define how connections are revoked when a customer disconnects or an account closes.
Keep credentials out of customer-visible content. Decide what diagnostic records may contain, who can view them and when they should be removed. A support record should explain a failure without unnecessarily copying personal information or secrets.
For a broader discussion of these decisions, see data security in modern applications.
What changes between sandbox and production?
Treat the sandbox as a place to test the workflow. Establish separately what evidence is needed before trusting the live connection.
Ask which differences apply:
- Account approval and permission requirements.
- Available features and supported data.
- Request limits and billing.
- Webhook configuration and delivery behaviour.
- Error responses and recovery tools.
Use separate test and live credentials, and make the active connection clear to the people operating it. Agree on a controlled production check with an authorised account and a reversible action where possible.
Success means more than receiving a successful response. Verify that the intended record exists, its status is correct and any resulting notification or charge matches the agreed action.
How will you handle API version changes?
Before choosing a provider, ask how it announces changes, which versions you can select and what happens when support for a version ends. Record the answers as evaluation evidence.
Assign someone to review those announcements. Include time for compatibility testing and updates in the ongoing service agreement.
Ask your build partner to keep provider-specific details behind a clear boundary in the application. Your product should have its own definition of an order, customer or shipment, with explicit rules for translating provider data.
That boundary gives future changes a defined place to happen. It should remain small: build around the provider and workflow you need today, with tests for the behaviour your product depends on.
What should the cost estimate include?
Request an estimate tied to a business action, such as completing an order, rather than a headline price per request.
Include initial requests, status checks, eligible retries and scheduled synchronisation. Verify which of those activities are billable under the provider's terms.
Also budget for development, monitoring, support, data retention and version upgrades. Ask what happens when a spending limit is reached: should work stop, queue or require approval?
Use clearly labelled assumptions for normal demand and a busy period. Keep provider charges separate from your own operating costs so changes are easier to explain.
How much vendor lock-in is acceptable?
Some dependence may be a reasonable trade for a capability you need. Make that trade explicit.
Before committing, establish:
- Which records you can export and in what form.
- Whether your product retains the identifiers needed to reconcile those records.
- Which features depend on provider-specific behaviour.
- How you would disconnect customers and revoke access.
- What a replacement would require.
Avoid building support for several providers merely as insurance. Write down an exit path, preserve necessary records and implement alternatives when there is a business reason.
What common mistakes should you avoid?
Treating every failure as retryable. Require a documented distinction between correcting input, restoring access, waiting and checking an uncertain outcome.
Making the user guess. Define separate messages for pending, completed and needs attention.
Stopping at the successful demonstration. Include duplicate submissions, interrupted requests, missed events and recovery in acceptance testing.
Leaving maintenance unowned. Name who handles provider notices, cost alerts and unresolved actions after launch.
What belongs on the API integration checklist?
Before approving the build, confirm:
- [ ] The customer workflow and pending states are defined.
- [ ] Limits have been checked against expected demand.
- [ ] Retry rules address uncertain outcomes.
- [ ] Webhook authentication, duplicates and recovery are covered.
- [ ] Permissions, credentials and diagnostic data have clear rules.
- [ ] Sandbox differences and live checks are documented.
- [ ] Version maintenance has an owner.
- [ ] Costs include ongoing operation and support.
- [ ] Data export and disconnection have an agreed path.
- [ ] Failure and recovery tests have clear pass conditions.
What else do founders ask about API integration?
Is a sandbox enough to approve launch?
Require evidence for both the tested workflow and the production-specific conditions. Agree on the live checks before launch.
Do all integrations need webhooks?
No. Choose notifications, scheduled checks or user-triggered requests according to the workflow and the provider's supported options.
Can an integration be estimated before choosing a provider?
Estimate the business workflow first. Keep provider-dependent work provisional until you have reviewed access, limits, failure behaviour and commercial terms.
If data flows both ways, see how to prevent conflicts in two-way sync and testing beyond the sandbox.
*Planning a product that depends on outside services? Start a conversation about the workflow, failure handling and ongoing costs.*