AGENT SKILL

platform-api-integration

Integrate with SaaS platform APIs — authentication, rate limits, webhooks, SDK patterns, and robust client design.

License 许可
MIT
所属仓库
TanNhatCMS/jarvis
最近更新
2026-11-07
Stars
★ 0
Forks
1

01 前言 Front Matter

name
platform-api-integration
category
curviate
description
Integrate with SaaS platform APIs — authentication, rate limits, webhooks, SDK patterns, and robust client design.

03 SKILL.md 正文

Overview

Integrating with a SaaS platform's API means: authenticating securely, handling rate limits, processing webhooks, and building clients that survive real-world failures. This skill covers general API integration patterns for SaaS platforms — vendor-neutral principles applicable to any REST/GraphQL API.

Integrating with SaaS platform APIs connects your product to the ecosystems where customers work: syncing data, embedding workflows, and extending capabilities. Good integrations feel native; bad ones feel bolted-on. This skill covers API integration strategy, implementation patterns, and the operational discipline of maintaining integrations over time.

When to use

  • Integrating with a third-party SaaS API

  • Designing API clients

  • Handling OAuth flows

  • Debugging rate limit issues

  • Building webhook receivers

  • Planning API version upgrades

  • Building native integrations with popular SaaS tools

  • Syncing data bidirectionally between platforms

  • Embedding third-party functionality via APIs

  • Designing integration marketplaces or app directories

Core concepts

Authentication. API keys (simple, server-to-server — store securely, rotate regularly), OAuth 2.0 (user-delegated access — authorization code flow for web, PKCE for mobile/SPA), and token management (secure storage, refresh before expiry, handle revocation). Never expose secrets client-side.

Rate limits. Understand: limits per window, per endpoint, per token. Handle 429s with exponential backoff + jitter, respect Retry-After headers, implement client-side throttling (token buckets), and batch requests where the API supports it. Design for limits from day one — retrofitting is painful.

Pagination. Cursor-based (preferred for large/changing datasets), offset-based (simple, breaks with concurrent writes), and page-size tuning. Always handle "more pages" loops defensively (max iterations, progress logging).

Error handling. Retry transient errors (5xx, 429, timeouts) with backoff; don't retry client errors (4xx — fix the request); parse error bodies for actionable codes; implement circuit breakers for cascading failures; and log request IDs for support.

Webhooks. Verify signatures, respond fast (2xx immediately, process async), dedupe on event IDs (at-least-once delivery), handle out-of-order events (idempotent processing), and build replay tooling. See webhook-patterns for depth.

Versioning and change management. Pin API versions, monitor deprecation notices, test against beta/sandbox before upgrades, and abstract version differences behind your client layer. Subscribe to API changelogs — breaking changes announced there first.

Integration patterns. Polling (simple, delayed, API-heavy) → webhooks (real-time, requires receiver infrastructure) → streaming (high-volume, ordered) → batch sync (large datasets, scheduled). Choose by freshness requirements and volume — webhooks for real-time needs, batch for analytics. Most integrations combine patterns: webhooks for events, batch for backfill. Authentication. OAuth 2.0 (user-delegated, standard for SaaS), API keys (server-to-server, simple), webhooks signatures (verify sender). Implement OAuth properly: secure token storage, refresh handling, scope minimization, and graceful re-auth flows. Token expiry mid-workflow is a top integration failure — handle refresh transparently. Rate limits and quotas. Every API throttles: understand limits (requests/minute, daily caps), implement backoff with jitter, queue and batch requests, cache aggressively. Design for the limit from day one — retrofitting throttling under load causes outages. Data mapping. Field-level mapping between systems with transformation rules, conflict resolution (last-write-wins? source priority?), and handling of custom fields. Document mappings explicitly; implicit mappings break silently when either API changes.

Practical workflow

  1. Read the docs. Authentication, rate limits, pagination, webhooks, error codes, versioning policy. Build a mental model before writing code.
  2. Design the client. Wrapper library with: auth handling, retry/backoff, rate-limit awareness, pagination helpers, error translation (API errors → domain exceptions), and request logging. One client, used everywhere — no ad-hoc HTTP calls scattered around.
  3. Implement auth. Secure credential storage (vaults, not env files in repos), token refresh logic, and scope minimization (request only needed permissions).
  4. Build defensively. Timeouts on every call, retries with backoff, circuit breakers, idempotency keys for writes, and graceful degradation (what happens when the API is down?).
  5. Handle data sync. Decide: real-time (webhooks), polling (for APIs without webhooks — respect intervals), or hybrid. Reconcile periodically (webhooks get missed; nightly syncs catch drift).
  6. Operate. Monitor: error rates, latency, rate-limit hits, webhook delivery. Alert on anomalies. Review API changelogs monthly; test version upgrades in sandbox first.

Client checklist: auth + refresh → retries with backoff → rate-limit handling → pagination helpers → timeout per call → error translation → request logging → idempotent writes → webhook verification.

Integration development: study API docs and changelog → prototype auth flow → map data models → build happy path → handle errors and edge cases → implement webhooks → build sync engine (initial + incremental) → test with real accounts → beta with design partners → launch with monitoring. Budget 40% of time for edge cases and error handling — happy paths are the easy part. Maintenance program: monitor API changelogs → track deprecation timelines → maintain version compatibility → handle credential expiry proactively → audit sync health daily. APIs change constantly; integrations are living systems, not shipped features.

Common pitfalls

  • Secrets in code. API keys committed to repos. Vaults + rotation, always.
  • No retry logic. Single attempt, fail loudly. Transient failures are normal — retry intelligently.
  • Ignoring rate limits. Hammering until banned. Backoff, throttle, batch.
  • Sync without reconciliation. Trusting webhooks alone. Periodic full syncs catch missed events.
  • No timeouts. Hanging requests consuming resources. Timeout everything.
  • Version drift. Running against deprecated versions until forced migration. Track versions proactively.
  • Scattered integration code. Ad-hoc API calls across the codebase. Centralize behind one client.
  • Underestimating API quality variance. Some APIs are excellent; others are buggy, slow, or poorly documented. Prototype early to discover reality before committing roadmaps.
  • No sync observability. Silent sync failures corrupting data for weeks. Monitor sync lag, error rates, and data consistency continuously.
  • Ignoring API terms. Rate limit violations, prohibited use cases, or data storage restrictions. Read the terms; violations get API access revoked.
  • Building on undocumented endpoints. They change without notice. Use public APIs only — or accept the maintenance burden explicitly.

04 同仓库更多 Skills

TanNhatCMS
TanNhatCMS/jarvis

web-scrape

Turn web pages into LLM-ready markdown via the Firecrawl API (renders JS, anti-bot handling). Use when browser_open/fetch fails on JS-heavy pages, or when you need clean markdown/structured extraction from a site. Requires FIRECRAWL_API_KEY.

★ 0
TanNhatCMS
TanNhatCMS/jarvis

design-taste-frontend

tasteskill v2, the anti-slop frontend skill. Art direction for websites, distilled from a study of 247 curated gallery sites (One Page Love, Awwwards Sites of the Day). Deals researched directions (idea, composition, type, palette, photographs, section blueprints) from a library, enforces a strict no-slop house style with a real-browser inspector, and runs a look-and-fix loop on screenshots. Use this whenever you build, design, redesign, restyle, polish or review a landing page, marketing site, portfolio, product page, one-pager, hero or any public-facing web page, in any stack (HTML/CSS, React, Next.js, Vue, Svelte, Astro, Tailwind) — also when the user says a page looks generic, templated, "AI-made", sloppy, or asks to make it look designed, premium, award-level or less like every other site. Not for dashboards or app screens.

★ 0
TanNhatCMS
TanNhatCMS/jarvis

test-driven-development

Use when implementing any feature or bugfix, before writing implementation code

★ 0
TanNhatCMS
TanNhatCMS/jarvis

systematic-debugging

Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes

★ 0
TanNhatCMS
TanNhatCMS/jarvis

requesting-code-review

Use when completing tasks, implementing major features, or before merging to verify work meets requirements

★ 0
TanNhatCMS
TanNhatCMS/jarvis

brainstorming

You MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).

★ 0