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
- Read API documentation completely
- Test auth flow (get valid token/key)
- Test each endpoint with curl/Postman first
- Implement error handling for all status code ranges
- Implement rate limit handling
- Implement retry logic with backoff
- Log all requests and responses (redact secrets)
- Handle API versioning (pin to specific version)
- Set timeouts (connect: 5s, read: 30s)
- 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
