Integrations are one of those areas where teams often underestimate complexity at first, then overcorrect after painful incidents.
The trap is familiar:
- Ship first integration fast
- Assume second one will be easier
- Discover every provider behaves differently
Even within the same category, semantics diverge. “ATS is ATS” does not hold in practice. The same goes for CRMs. Object models, lifecycle behavior, permissions, webhook design, and pagination details can all differ enough to break naive assumptions.
Separate the two muscles: consuming and providing
One useful framing for integration work is to separate two roles:
- consuming third-party APIs
- providing your own API and webhook platform
When consuming, you inherit someone else’s constraints: rate limits, ambiguous semantics, uneven docs, and partial failures.
When providing, you become the platform and own contract stability, retries, idempotency behavior, and operational clarity for your users.
Treating those roles as the same problem causes design confusion. Keeping them explicit improves architecture and ownership boundaries.
Canonical internal model plus adapters
To avoid building every feature against raw provider semantics, I use a canonical internal model with provider adapters.
Important caveat: canonical does not mean universal truth. It is an internal interface boundary that stabilizes your product.
The adapter layer is where provider-specific behavior lives:
- field mapping and transformation
- pagination and incremental sync mechanics
- lifecycle and state machine differences
- webhook normalization
This keeps complexity localized and makes provider-specific bugs easier to reason about.
Store enough raw context to debug and replay
Integration incidents are rarely solved by clean abstractions alone. You need forensic data.
For each connector path, capture:
- source object IDs
- sync checkpoints
- raw payload snapshots
- processing outcomes and error class
When a customer says “records are missing,” this gives you a direct path to diagnosis instead of guesswork.
Standards first, custom behavior second
If there is a meaningful standard, use it. If not, align with user expectations and document the differences clearly.
The long-term cost of “almost standard” custom behavior is high:
- higher onboarding friction
- more edge-case support tickets
- harder long-term maintenance
Explicit mapping documentation is better than pretending different models are equivalent.
OAuth is not just auth, it is lifecycle and security
In integration platforms, OAuth is operational infrastructure:
- token refresh and rotation
- revocation handling
- redirect URI safety
- state parameter protection
- scope discipline and least privilege
- secure token storage
Security and lifecycle bugs here are expensive and user-visible, so these paths need the same engineering rigor as core business logic.
AI-assisted SOQL: treat it as safety and performance
One useful but risky feature was helping users generate Salesforce queries with AI.
If you let users generate raw SOQL without guardrails, you inherit query performance risk and support burden. So this was handled as constrained generation:
- encourage selective filters
- avoid unbounded scans
- bias toward indexed fields when possible
- reject or rewrite unsafe query shapes
The goal was not “any query succeeds.” The goal was “safe query patterns are the default.”
Outcome: integrations became a platform, not a queue of one-offs
The biggest shift was not one connector shipping faster. It was architectural.
With adapter boundaries, idempotency and retry standards, replay support, telemetry, and OAuth guardrails, integration delivery became repeatable.
That produced practical improvements:
- faster onboarding to first successful sync
- lower incident resolution time
- clearer support diagnostics
- less rework per new connector
You still should not assume the next integration is easy. But you can stop relearning the same reliability lessons from scratch.
References
- OAuth 2.0 Cheat Sheet (OWASP)
- OAuth 2.0 Security Best Current Practice (RFC 9700)
- Salesforce large data volume guidance for SOQL
Related case study
Integration Platform (ATS and CRM, OAuth, Operational Guardrails)