api-integration-patterns_skill

Overview

This skill provides unified, production-ready patterns for integrating external OAuth2 APIs in laneweaverTMS. It codifies token lifecycle management, exponential backoff with jitter, webhook vs polling guidance, rate limiting strategies, error handling taxonomy, multi-tenant isolation, and webhook security. Use these patterns to reduce surprises and improve reliability across QuickBooks, MyCarrierPackets, Slack, and other OAuth2 providers.

How this skill works

The skill inspects common integration concerns and supplies concrete patterns and code sketches you can reuse in Go. It covers token storage and proactive refresh, retry and circuit-breaker composition, hybrid webhook/polling sync, token-bucket and header-driven rate limiting, and structured error categorization. Each pattern includes practical rules (when to refresh, retryable status codes, polling fallbacks) and recommended concurrency controls for multi-tenant environments.

When to use it

• Implementing OAuth2 flows and multi-tenant token isolation
• Building robust retry logic with exponential backoff and jitter
• Choosing between webhooks and polling for sync reliability
• Designing client-side rate limiting and request queues
• Implementing webhook security and replay protection
• Standardizing error handling and circuit breaker integration

Best practices

• Store access and refresh tokens encrypted in the database; never in JWTs or browser storage
• Refresh access tokens proactively (e.g., at 80% of lifetime) and double-check under lock to avoid thundering refreshes
• Retry with exponential backoff plus jitter and limit retries; treat 429 and 5xx as retryable
• Combine backoff with a circuit breaker to prevent cascading failures
• Use webhooks for real-time updates and polling as a backup for missed events and initial backfill
• Parse provider rate-limit headers and enforce a client-side token-bucket to protect shared quotas

Example use cases

• QuickBooks: persist tenant-scoped OAuth tokens, refresh proactively, and use webhook+polling to keep ledgers in sync
• Slack: respect Retry-After, apply token-bucket limits for high-volume bots, and secure event endpoints with signatures
• MyCarrierPackets: use polling for large batch syncs and webhooks for urgent status updates, with reconciliation on failure
• laneweaverTMS multi-tenant: isolate tokens per account, queue prioritized requests, and apply circuit breakers per external provider