Howmany-Zeta API Integration Skill
This skill provides patterns and best practices for building robust API integrations in Python applications.
When to Use This Skill
Use this skill when you need to:
- Build HTTP clients to consume REST APIs
- Implement authentication flows (API keys, OAuth, JWT)
- Handle API errors gracefully with retries
- Manage rate limiting and throttling
- Parse and validate API responses
HTTP Client Best Practices
Client Setup
- Use a session for connection pooling - Reuse connections for better performance
- Set appropriate timeouts - Always configure connect and read timeouts
- Configure base URLs - Use a base URL to avoid repetition
- Add default headers - Include User-Agent, Accept, and Content-Type headers
Request Handling
- Validate inputs before sending - Check required parameters
- Use appropriate HTTP methods - GET for reads, POST for creates, etc.
- Handle query parameters properly - Use library features, don't concatenate strings
- Stream large responses - Don't load large files entirely into memory
Response Processing
- Check status codes first - Handle 4xx and 5xx errors appropriately
- Parse JSON safely - Handle malformed JSON responses
- Validate response schema - Ensure responses match expected format
- Log important details - Request ID, timing, status for debugging
Error Handling Strategies
Retry Logic
Implement exponential backoff for transient errors:
- Retry on: 429 (Too Many Requests), 500, 502, 503, 504
- Don't retry on: 400, 401, 403, 404 (client errors)
- Use exponential backoff: Start with 1s, double each retry
- Set max retries: Typically 3-5 attempts
Circuit Breaker Pattern
Prevent cascading failures:
- Track consecutive failures
- Open circuit after threshold (e.g., 5 failures)
- Allow limited requests during half-open state
- Close circuit after successful requests
Graceful Degradation
When APIs are unavailable:
- Return cached data if available
- Provide meaningful error messages
- Log failures for monitoring
- Consider fallback services
Available Resources
See references/api-patterns.md for detailed implementation patterns.
See examples/api-client-example.py for working code examples.
Use scripts/test-endpoint.sh to test API endpoints.