home / skills / vadimcomanescu / codex-skills / api-integration-specialist

api-integration-specialist skill

safe

/skills/.experimental/ai/api-integration-specialist

This skill helps you build reliable API integrations with strong auth, error handling, retries, and boundary payload transformations.

npx playbooks add skill vadimcomanescu/codex-skills --skill api-integration-specialist

Review the files below or copy the command above to add this skill to your agents.

Files (3)

SKILL.md

1.5 KB

---
name: api-integration-specialist
description: Expert in integrating third-party APIs with proper authentication, error handling, rate limiting, and retry logic. Use when integrating REST APIs, GraphQL endpoints, webhooks, or external services. Specializes in OAuth flows, API key management, request/response transformation, and building robust API clients.
---

# API Integration Specialist

Build reliable integrations with clear auth, error handling, and rate limit safety.

## Quick Start
1) Read the provider’s auth + rate limit docs.
2) Design a thin client with retries and typed errors.
3) Transform provider payloads to internal models at the boundary.
4) Add tests: happy path, auth failure, rate limit, and server error.

## Integration Checklist
- **Auth**: API key vs OAuth; store secrets in env; rotate safely.
- **Errors**: map status codes to typed errors; include response body.
- **Retries**: exponential backoff on 429/5xx; respect `Retry-After`.
- **Webhooks**: verify signatures; idempotency; replay-safe handlers.
- **Pagination**: cursor/offset; avoid unbounded loops.
- **Timeouts**: set sane timeouts per call.

## Boundary Pattern (example)
```ts
async function request(path, init) {
  const res = await fetch(`${baseUrl}${path}`, init);
  if (!res.ok) throw new ApiError(res.status, await res.json());
  return res.json();
}
```

## Guardrails
- Never log secrets.
- Keep provider-specific logic at the boundary.
- When requirements are unclear, ask for target SLAs and expected volume.

## References
- Extended examples: `references/examples.md`

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

FAQ

How should secrets be stored and rotated?

Keep secrets in environment variables or a secrets manager, automate rotation, and ensure clients can hot-reload credentials when rotated.

Which errors should trigger retries?

Retry on 429 and most 5xx server errors with exponential backoff and jitter; do not retry on 4xx client errors except when retryable semantics are documented.

How do I verify webhooks safely?

Verify signatures using the provider’s algorithm, reject mismatches, and design handlers to be idempotent and safe to replay.