In over a decade of integrating external APIs, one pattern keeps repeating: 80% of production issues could have been avoided with a simple 15-minute review. Here is the exact checklist I use before plugging any new API into a client's system.
Context
I have integrated everything from legacy XML web services for telcos in the late 2000s to Stripe, logistics couriers, CRMs, maps, and a few others I would rather not name publicly. This checklist evolved with every incident: the day a rate limit brought down our checkout, the day an unannounced breaking API change locked us out of a critical workflow, and the day a webhook silently failed and we only found out because a customer called.
This is not theory. It is what I wish I had on day one.
The Checklist
1. Before Signing (Vendor Vetting)
- Authentication & Rotation: Is it API Key, OAuth, JWT, or mTLS? How do you rotate credentials in production without downtime? If the answer is "open a support ticket," that is a major red flag.
- Rate Limits & Quotas: Are limits per minute, day, or month? What happens when you exceed them? Do they warn you, or do they cut you off cold?
- Versioning & Deprecation: How long do they support older versions? How are deprecations announced? Is there a public changelog?
- Sandbox & Test Data: Do they provide a realistic test environment, or just a broken endpoint with mock data? Are test cards standardized or proprietary?
- Real Pricing: What is the cost at your expected volume? Are there hidden tiers? What does it cost to scale 10x?
- Status Page & SLA: Do they have a public status page? Is there a contractual SLA? Were there major outages in the last year (check Hacker News or GitHub issues)?
- Compliance & Data Privacy: Where is data stored? Do they comply with GDPR, HIPAA, or local regulations as needed? Handling customer data makes this non-negotiable.
2. During Integration
- Idempotency Keys from Day One: Any operation that creates or updates state must be safely repeatable without side effects. Stripe enforces this, but many vendors do not, leaving you exposed to duplicate charges or actions.
- Retries with Exponential Backoff + Jitter: Cap retries at three attempts with exponential delay. Anything more usually hides a deeper issue.
- Explicit Timeouts: Short connection timeouts (1 to 2 seconds) and operation-specific read timeouts. Default SDK settings are often 30 seconds or infinite, both of which are dangerous.
- Input Validation Before Requests: Never send invalid payloads to a vendor. You still get charged or hit rate limits for malformed requests.
- Structured Logging with Correlation IDs: Attach a unique ID to every outgoing request that passes through your logs and the vendor's logs. When something breaks, cross-referencing takes seconds.
3. Before Going to Production
- Mocks & Contract Tests: Mock all external calls in unit tests, and add contract tests (using tools like Schemathesis) to detect unannounced schema changes early.
- - Dry-Run Mode or Staging: Test full end-to-end user flows in a realistic staging environment, focusing on failure cases rather than just the happy path.
- Rollback & Degradation Plan: If the vendor goes down, can your application operate in a degraded state? If not, you have introduced a single point of failure.
- Actionable Alerting: Set alerts for error rates exceeding thresholds, high latency, or quota limits reaching 80%.
- Internal Documentation: Keep a single page detailing what the integration does, where the code lives, key rotation procedures, scaling limits, and emergency playbooks.
4. Post-Production Operations
- Real-Time Dashboards: Track success rates, latency distribution, and quota consumption instead of relying on log searching.
- Targeted Alerts: Avoid generic alerts like "API returned 500." Use actionable alerts such as "API error rate exceeded 5% over the last 10 minutes."
- Quarterly Vendor Reviews: Re-evaluate pricing, version updates, new rate limits, and company health every three months.
- Quarterly Vendor Reviews: Re-evaluate pricing, version updates, new rate limits, and company health every three months.
Final Thoughts
This checklist does not guarantee zero outages, but it turns catastrophic crashes into manageable incidents with clear recovery plans. The difference between those two outcomes is what separates professional engineering from guesswork.
Evaluating a vendor remains a fundamentally human task. AI can help write contract tests or generate client wrappers, but deciding whether a service is trustworthy, secure, and sustainable requires real human judgment.