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

# 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