api-integration-specialist_skill

Overview

This skill helps build reliable third-party API integrations with correct authentication, robust error handling, rate limit safety, and clear request/response transformation. It focuses on practical patterns for REST, GraphQL, and webhook integrations and provides guidance for OAuth flows, API key management, retries, and typed errors. Use it to design maintainable API clients that are safe in production.

How this skill works

I inspect provider documentation and implement a thin boundary client that centralizes auth, timeouts, retries, and error mapping. The client transforms provider payloads into internal models at the boundary and enforces guardrails like secret handling and replay-safe webhook processing. I include test cases for happy paths and failure modes and recommend configuration via environment variables and SLAs.

When to use it

• Integrating REST or GraphQL endpoints into backend services
• Implementing OAuth flows or managing API keys and secret rotation
• Creating or consuming webhooks with signature verification and idempotency
• Building resilient clients that must handle rate limits and transient failures
• Designing pagination, timeout, and retry strategies for high-volume traffic

Best practices

• Centralize provider-specific logic at a single client boundary to simplify testing and replacement
• Store secrets in environment variables or a secrets manager; never log secrets
• Map HTTP status codes to typed errors and include sanitized response details for debugging
• Implement exponential backoff and respect Retry-After for 429/5xx responses; limit total retry time
• Verify webhook signatures, enforce idempotency, and design handlers to be replay-safe
• Set sensible per-call timeouts and test for pagination edge cases to avoid unbounded loops

Example use cases

• Build a thin Python client for a payments API with OAuth2 refresh token handling and typed error classes
• Create a webhook consumer that verifies HMAC signatures, persists events idempotently, and supports replay protection
• Wrap a third-party GraphQL endpoint with a boundary that normalizes response shapes and implements cursor pagination
• Add retry and circuit-breaker logic for a rate-limited analytics ingestion endpoint
• Design tests covering auth failure, rate limit responses, server errors, and successful pagination