# API

> Consume, debug, and integrate REST APIs with best practices.

- Skill: `zangxin75/api` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds add zangxin75/api`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zangxin75/api/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: zangxin75 (https://skillmd.com/u/zangxin75)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/zangxin75/api

---


# API Integration Rules

## Request Gotchas
- Include `Content-Type: application/json` on POST/PUT/PATCH — omitting it causes silent 415 errors on many APIs
- Add `Accept: application/json` unless the API specifies a different format — some default to XML without it
- API keys in query params get logged in server access logs — prefer header-based auth when supported
- Tokens can expire mid-flight between request and response — handle 401 with single retry + refresh

## Silent Failures
- Some APIs return HTTP 200 with error in response body — validate response schema, not just status code
- Watch for empty arrays vs null vs missing keys — each means something different per API
- Paginated endpoints may return 200 with empty page when offset exceeds total — check total count first

## Retry and Resilience
- Use jittered exponential backoff: `delay = min(base * 2^attempt * (1 + random(0, 0.3)), max_delay)` with base=1s, max=30s
- Generally only retry on 429, 500, 502, 503, 504 — avoid retrying 400, 401, 403, 404 unless the API documents otherwise
- Read `Retry-After` header on 429 — it overrides your calculated backoff
- After 5+ consecutive failures to the same endpoint, back off entirely for 60s before retrying (circuit breaker)

## Pagination Traps
- Cursor-based pagination can return duplicate items if data changes between pages — deduplicate by ID
- Some APIs change `total_count` between requests — snapshot it on first page
- If page returns fewer items than `per_page` but includes a `next` cursor, keep paginating — it's not necessarily the last page

## Rate Limiting
- Track quota via `X-RateLimit-Remaining` header — throttle proactively before hitting 0, don't wait for 429
- Some APIs have hidden per-endpoint rate limits, not just global — monitor 429s per path
- Distribute requests evenly across the rate window instead of bursting at the start

## Webhooks
- Implement idempotent handlers with event ID dedup — providers retry on timeout and you'll get duplicates
- Return 200 immediately, process asynchronously — webhook providers timeout at 5-30s
- Verify webhook signatures when the provider supports them — don't trust payload origin without cryptographic proof
- Log the raw webhook body before parsing — invaluable when the provider changes their schema without notice

## Debugging Production Issues
- Log: method, URL, status code, response time, and `X-Request-Id` header for every API call
- APIs that work in dev but fail in prod: check IP allowlists, TLS version, SNI, and egress proxy settings
- When response data looks wrong, compare against the OpenAPI/Swagger spec — the spec is often more current than human-written docs