Tech API Integration

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

Status Codes

Authentication Types

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

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