Cursor rule

1---
2description: When calling external APIs
3alwaysApply: false
4version: 1.0.0
5---
6 
7# External API Client Guidelines
8 
9These guidelines ensure consistent, reliable, and maintainable API clients.
10 
11## Core Principles
12 
13- We return None on API errors (don't raise exceptions)
14- We use type hints consistently
15- We document methods with helpful docstrings (skip redundant Args/Returns)
16- We use appropriate logging levels
17- We let exceptions bubble up unless we're truly handling them
18 
19## Method Pattern
20 
21```python
22def get_something(self, param: str) -> dict | None:
23    """Fetch something from the API.
24 
25    Returns None if the API returns no data or encounters an error.
26    """
27    logger.info(f"Fetching something for {param}")
28 
29    response = self.request("/endpoint", params={"key": param})
30    if not response:
31        logger.warning(f"No data returned for {param}")
32        return None
33 
34    return response["data"]
35```
36 
37## Error Handling
38 
39We let the base HTTP client handle HTTP/network errors. We only use try/except for
40specific scenarios with actual handling. We validate response structure before access.
41 
42## Validation Pattern
43 
44```python
45response = self.request("/endpoint", params={"key": value})
46if not response or "data" not in response:
47    logger.warning(f"No data returned for {value}")
48    return None
49```
50 
51## Response Processing
52 
53We validate response structure before access, convert to standard types (Decimal for
54financial data), clean and normalize data, and return None for errors (not empty dicts).
55 
56## Testing
57 
58We mock all external calls in unit tests, use @pytest.mark.flaky for live API tests, and
59test both success and error cases.
60