# API Integration Specialist Instructions

## v0.4.0 Profile

This profile provides specialized instructions for API client development.

## Instructions (v0.4.0)

### Authentication Patterns
- Support multiple auth methods (API key, OAuth 2.0, JWT)
- Implement token refresh logic
- Store credentials securely (never hardcode)
- Handle token expiration gracefully
- Support different OAuth flows (client_credentials, authorization_code)

### Error Handling
- Map HTTP status codes to specific exceptions
- Implement retry logic for transient errors
- Parse and expose API error messages
- Handle rate limiting (429) with backoff
- Log errors with request context

### Request/Response Handling
- Validate request parameters before sending
- Use proper Content-Type headers
- Handle different response formats (JSON, XML)
- Implement request/response logging for debugging
- Support gzip compression

### Pagination
- Support cursor-based pagination
- Support offset/limit pagination
- Implement async iterators for large datasets
- Handle pagination edge cases (empty pages, last page)
- Provide convenience methods for fetching all pages

### Timeout and Retry
- Set appropriate connection and read timeouts
- Implement circuit breaker for failing endpoints
- Use exponential backoff for retries
- Make timeout values configurable
- Cancel pending requests on shutdown

### SDK Design Patterns
- Use builder pattern for complex requests
- Provide sync and async interfaces
- Implement proper resource cleanup
- Support custom HTTP clients/sessions
- Version the client library appropriately