REST API Integration Guide

Framework

IRON LAW: Read the Docs, Then Build, Then Handle Errors

1. Read the API documentation completely (auth, endpoints, rate limits, errors)
2. Get a successful request working in isolation (curl/Postman)
3. Build error handling BEFORE building features

Skipping step 1 wastes hours on trial-and-error. Skipping step 3
creates fragile integrations that break silently in production.

HTTP Methods

| Method | Purpose | Idempotent? | Example | |--------|---------|------------|---------| | GET | Read data | Yes | GET /users/123 | | POST | Create new resource | No | POST /users + body | | PUT | Replace entire resource | Yes | PUT /users/123 + full body | | PATCH | Update partial resource | Yes | PATCH /users/123 + partial body | | DELETE | Remove resource | Yes | DELETE /users/123 |

Status Codes

| Range | Meaning | Common Codes | |-------|---------|-------------| | 2xx | Success | 200 OK, 201 Created, 204 No Content | | 3xx | Redirect | 301 Moved, 304 Not Modified | | 4xx | Client error (your fault) | 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 429 Too Many Requests | | 5xx | Server error (their fault) | 500 Internal, 502 Bad Gateway, 503 Service Unavailable |

Authentication Types

| Type | How It Works | When Used | |------|-------------|----------| | API Key | Key in header or query param | Simple APIs, server-to-server | | Bearer Token | Authorization: Bearer <token> | OAuth 2.0, JWT-based APIs | | OAuth 2.0 | Token exchange flow (authorize → token → API call) | User-delegated access (Google, FB) | | Basic Auth | Base64(username:password) in header | Legacy, internal APIs | | HMAC Signature | Sign request with secret key | Payment gateways, high-security |

Error Handling Strategy

try:
    response = api.call(request)
    if response.status == 429:  # Rate limited
        wait(response.headers['Retry-After'])
        retry()
    elif response.status >= 500:  # Server error
        retry_with_backoff(max_retries=3)
    elif response.status >= 400:  # Client error
        log_error(response.body)
        raise ClientError(response.body['message'])
    else:
        return response.json()

Rate Limiting

| Strategy | How | |----------|-----| | Respect Retry-After header | Wait the specified seconds before retrying | | Exponential backoff | Wait 1s, 2s, 4s, 8s between retries | | Token bucket | Track request count, pause when approaching limit | | Queue requests | Use a job queue (Celery, Bull) for high-volume integrations |

Integration Checklist

1. ] Read API documentation completely
2. ] Test auth flow (get valid token/key)
3. ] Test each endpoint with curl/Postman first
4. ] Implement error handling for all status code ranges
5. ] Implement rate limit handling
6. ] Implement retry logic with backoff
7. ] Log all requests and responses (redact secrets)
8. ] Handle API versioning (pin to specific version)
9. ] Set timeouts (connect: 5s, read: 30s)
10. ] Monitor for API deprecation notices

Output Format

markdown
# API Integration Plan: {API Name}

## API Overview
- Base URL: {url}
- Auth: {type}
- Rate limit: {N requests/period}
- Documentation: {link}

## Endpoints Used
| Endpoint | Method | Purpose | Auth |
|----------|--------|---------|------|
| {path} | GET/POST | {what it does} | {auth type} |

## Error Handling
| Error | Response | Our Action |
|-------|----------|-----------|
| 401 | Unauthorized | Refresh token, retry |
| 429 | Rate limited | Backoff, retry after Retry-After |
| 500 | Server error | Retry 3x with exponential backoff |

## Implementation Timeline
| Phase | Task | Duration |
|-------|------|----------|
| 1 | Auth + basic call | {days} |
| 2 | Full integration | {days} |
| 3 | Error handling + monitoring | {days} |

Gotchas

• Sandbox vs production: Most APIs have a sandbox/test environment. Build and test there first. Production API keys should never be in code.
• Pagination: APIs return paginated results. Handle all pages, not just the first. Check for next_page token or offset parameter.
• Webhook reliability: If using webhooks, implement idempotent handlers (same event received twice should not duplicate data). Store event IDs to deduplicate.
• API changes break things: Pin to a specific API version. Subscribe to the provider's changelog/deprecation notices.
• Secrets management: API keys and tokens NEVER in source code. Use environment variables or a secrets manager (AWS Secrets Manager, HashiCorp Vault).

References

• For OAuth 2.0 flow details, see references/oauth-guide.md
• For webhook implementation patterns, see references/webhook-patterns.md