engineering
API Integration Guide
Create REST and GraphQL integration guides covering authentication flows, pagination strategies, rate limiting, error handling, retry logic, and SDK wrapper patterns. Produces implementation-ready reference documents with code examples.
apirestgraphqlintegrationauthenticationrate-limitingpagination
Works well with agents
Works well with skills
$ npx skills add The-AI-Directory-Company/(…) --skill api-integration-guideSKILL.md
Markdown
| 1 | |
| 2 | # API Integration Guide |
| 3 | |
| 4 | ## Before you start |
| 5 | |
| 6 | Gather the following from the user: |
| 7 | |
| 8 | 1. **Which API?** (Service name, base URL, documentation link) |
| 9 | 2. **REST or GraphQL?** (Or both) |
| 10 | 3. **Authentication method?** (API key, OAuth 2.0, JWT, mTLS) |
| 11 | 4. **Which operations?** (List the endpoints or queries/mutations needed) |
| 12 | 5. **Client environment?** (Server-side, browser, mobile, CLI) |
| 13 | 6. **Error budget?** (Acceptable failure rate, timeout thresholds) |
| 14 | |
| 15 | If the user says "integrate with X API," push back: "Which specific operations do you need? I need the endpoints, auth method, and where this runs to write a useful guide." |
| 16 | |
| 17 | ## Procedure |
| 18 | |
| 19 | ### Step 1: Document the authentication flow |
| 20 | |
| 21 | For each auth method, produce the exact sequence: |
| 22 | |
| 23 | **API Key:** Document header name (`Authorization: Bearer <key>` or `X-API-Key`), storage (environment variable, never committed), and rotation procedure. |
| 24 | |
| 25 | **OAuth 2.0 (Authorization Code):** Document the full redirect-exchange-refresh cycle: authorize URL with state param, code exchange at token endpoint, refresh_token storage (encrypted), and proactive refresh before `expires_in`. |
| 26 | |
| 27 | **OAuth 2.0 (Client Credentials):** Document token endpoint call, cache duration (`expires_in` minus 60s buffer), and re-fetch on 401. |
| 28 | |
| 29 | ### Step 2: Map each operation |
| 30 | |
| 31 | For every endpoint or query, document: |
| 32 | |
| 33 | ``` |
| 34 | Operation: [Human-readable name] |
| 35 | Method: [GET/POST/PUT/PATCH/DELETE] or [Query/Mutation] |
| 36 | Path: [/resource/:id] or [GraphQL operation name] |
| 37 | Request: |
| 38 | Headers: [Required headers beyond auth] |
| 39 | Params: [Path, query, or body params with types and constraints] |
| 40 | Body example: [JSON] |
| 41 | Response: |
| 42 | Success (2xx): [Shape with field types] |
| 43 | Error codes: [4xx/5xx with meaning and action] |
| 44 | Rate limit: [Requests per window, header names for remaining/reset] |
| 45 | ``` |
| 46 | |
| 47 | ### Step 3: Design pagination handling |
| 48 | |
| 49 | Document the pagination pattern the API uses and how to consume it: |
| 50 | |
| 51 | - **Offset-based:** `GET /items?limit=100&offset=0`. Stop when response count < limit or offset >= total_count. |
| 52 | - **Cursor-based:** `GET /items?limit=100&cursor=<next_cursor>`. Stop when next_cursor is null. |
| 53 | - **GraphQL relay:** Use `pageInfo { hasNextPage endCursor }`. Stop when `hasNextPage` is false. |
| 54 | |
| 55 | For all patterns: state the maximum page size, recommend a default, and note whether the API supports parallel page fetching safely. |
| 56 | |
| 57 | ### Step 4: Implement rate limiting |
| 58 | |
| 59 | Document the API's rate limit response and the client-side strategy: |
| 60 | |
| 61 | ``` |
| 62 | Rate limit signal: |
| 63 | HTTP 429 Too Many Requests |
| 64 | Headers: X-RateLimit-Remaining, X-RateLimit-Reset (Unix timestamp) |
| 65 | |
| 66 | Client strategy: |
| 67 | 1. Before each request: check remaining count from last response headers. |
| 68 | 2. If remaining < 5: sleep until reset timestamp + 1 second jitter. |
| 69 | 3. On 429 response: read Retry-After header. Sleep for that duration. |
| 70 | 4. If no Retry-After: exponential backoff starting at 1s, max 60s. |
| 71 | 5. For batch operations: use a token bucket or leaky bucket limiter. |
| 72 | ``` |
| 73 | |
| 74 | ### Step 5: Design error handling and retries |
| 75 | |
| 76 | Classify errors and define behavior for each: |
| 77 | |
| 78 | | Status | Category | Retryable | Action | |
| 79 | |--------|----------|-----------|--------| |
| 80 | | 400 | Client error | No | Log payload, fix request, do not retry | |
| 81 | | 401 | Auth expired | Once | Refresh token, retry once | |
| 82 | | 403 | Forbidden | No | Log, alert, check permissions | |
| 83 | | 404 | Not found | No | Handle as missing resource | |
| 84 | | 409 | Conflict | Maybe | Re-fetch resource, resolve, retry | |
| 85 | | 429 | Rate limited | Yes | Backoff per rate limit strategy | |
| 86 | | 500 | Server error | Yes | Exponential backoff, max 3 retries | |
| 87 | | 502/503 | Unavailable | Yes | Exponential backoff, max 5 retries | |
| 88 | | Timeout | Network | Yes | Retry with same backoff as 5xx | |
| 89 | |
| 90 | Retry formula: `delay = min(base * 2^attempt + random_jitter_ms, max_delay)` |
| 91 | |
| 92 | ### Step 6: Write the SDK wrapper pattern |
| 93 | |
| 94 | The client wrapper should encapsulate: rate limiter wait before each request, retry loop with exponential backoff, automatic token refresh on 401 (once), error classification (retryable vs terminal), and a `paginate` method that loops cursor-based requests until exhausted. Constructor validates base_url, credentials, timeout, and max_retries. |
| 95 | |
| 96 | ## Quality checklist |
| 97 | |
| 98 | Before delivering the integration guide, verify: |
| 99 | |
| 100 | - [ ] Auth flow documents every step from credential acquisition to token refresh |
| 101 | - [ ] Every operation lists request shape, success response, error codes, and rate limit |
| 102 | - [ ] Pagination strategy handles the last page correctly and avoids infinite loops |
| 103 | - [ ] Rate limiting covers both proactive throttling and reactive 429 handling |
| 104 | - [ ] Error classification covers all common status codes with retry/no-retry decisions |
| 105 | - [ ] Retry logic uses exponential backoff with jitter, not fixed delays |
| 106 | - [ ] Credentials are never hardcoded; storage and rotation are documented |
| 107 | |
| 108 | ## Common mistakes |
| 109 | |
| 110 | - **Ignoring token expiry.** Caching an access token without monitoring `expires_in` leads to cascading 401s. Always refresh proactively. |
| 111 | - **Retrying 400 errors.** A malformed request will fail every time. Retrying wastes quota and delays error detection. |
| 112 | - **Fixed retry delays.** `sleep(5)` between retries causes thundering herd when multiple clients hit rate limits simultaneously. Use exponential backoff with random jitter. |
| 113 | - **Pagination off-by-one.** Forgetting to check the last page condition causes either an infinite loop or a missed final page. Test with 0, 1, and exactly-one-page result sets. |
| 114 | - **No timeout on HTTP calls.** A missing timeout means a hung connection blocks the caller indefinitely. Set connect and read timeouts explicitly. |
| 115 | - **Swallowing error response bodies.** The API often returns structured error details in the body. Log the full response, not just the status code. |
| 116 |