api-integration-guide

API Integration Guide

Before you start

Gather the following from the user:

1. Which API? (Service name, base URL, documentation link)
2. REST or GraphQL? (Or both)
3. Authentication method? (API key, OAuth 2.0, JWT, mTLS)
4. Which operations? (List the endpoints or queries/mutations needed)
5. Client environment? (Server-side, browser, mobile, CLI)
6. Error budget? (Acceptable failure rate, timeout thresholds)

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."

Procedure

Step 1: Document the authentication flow

For each auth method, produce the exact sequence:

API Key: Document header name (Authorization: Bearer <key> or X-API-Key), storage (environment variable, never committed), and rotation procedure.

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.

OAuth 2.0 (Client Credentials): Document token endpoint call, cache duration (expires_in minus 60s buffer), and re-fetch on 401.

Step 2: Map each operation

For every endpoint or query, document:

Operation: [Human-readable name]
Method: [GET/POST/PUT/PATCH/DELETE] or [Query/Mutation]
Path: [/resource/:id] or [GraphQL operation name]
Request:
  Headers: [Required headers beyond auth]
  Params: [Path, query, or body params with types and constraints]
  Body example: [JSON]
Response:
  Success (2xx): [Shape with field types]
  Error codes: [4xx/5xx with meaning and action]
Rate limit: [Requests per window, header names for remaining/reset]

Step 3: Design pagination handling

Document the pagination pattern the API uses and how to consume it:

• Offset-based: GET /items?limit=100&offset=0. Stop when response count < limit or offset >= total_count.
• Cursor-based: GET /items?limit=100&cursor=<next_cursor>. Stop when next_cursor is null.
• GraphQL relay: Use pageInfo { hasNextPage endCursor }. Stop when hasNextPage is false.