Cursor rule

1---
2description: UniFi API integration guidelines and patterns
3globs: ["src/api/**/*.py", "src/tools/**/*.py"]
4alwaysApply: true
5---
6 
7# UniFi API Guidelines
8 
9## Authentication with API Keys
10 
11This project uses the **official UniFi Cloud API** with API key authentication.
12 
13**Authentication Method:**
14 
15- Use `UNIFI_API_KEY` environment variable for authentication
16- API key is passed via the `X-API-Key` HTTP header
17- No session management or cookies required (stateless authentication)
18 
19**NEVER hardcode API keys:**
20 
21```python
22# ❌ BAD - Hardcoded API key
23headers = {
24    "X-API-Key": "abc123def456..."
25}
26 
27# ✅ GOOD - Load from environment
28from src.config.config import Settings
29 
30settings = Settings()
31headers = {
32    "X-API-Key": settings.api_key
33}
34```
35 
36## API Access Modes
37 
38Support both cloud and local gateway access modes:
39 
40**Cloud API (Default):**
41```python
42# Base URL: https://api.ui.com/v1/
43settings.api_type = "cloud"
44settings.cloud_api_url = "https://api.ui.com"
45```
46 
47**Local Gateway Proxy:**
48```python
49# Base URL: https://{gateway-ip}/proxy/network/integration/v1/
50settings.api_type = "local"
51settings.local_host = "192.168.2.1"
52settings.local_port = 443
53```
54 
55## Read-Only Limitation
56 
57**IMPORTANT:** The Early Access API is currently **read-only**.
58 
59```python
60# ✅ ALLOWED - Read operations
61async def list_devices(site_id: str):
62    """List all devices - read operation."""
63    devices = await client.get(f"/v1/sites/{site_id}/devices")
64    return devices
65 
66# ❌ NOT AVAILABLE - Write operations (will fail)
67async def create_network(name: str, vlan_id: int):
68    """Create network - not yet supported in EA API."""
69    # This will return 403 Forbidden in current API version
70    raise NotImplementedError(
71        "Write operations are not available in the Early Access API. "
72        "This feature will be available in v1 Stable release."
73    )
74```
75 
76**Handling write requests:**
77 
78- Document that write operations are not yet available
79- Return clear error messages to users
80- Consider implementing a "preview" mode that shows what would be created
81- Monitor UniFi API release notes for v1 Stable availability
82 
83## Rate Limiting Considerations
84 
85Implement proper rate limiting to respect API limits:
86 
87**Current Limits:**
88 
89- Early Access: 100 requests/minute
90- v1 Stable (future): 10,000 requests/minute
91 
92**Best Practices:**
93 
94- Cache frequently accessed data (devices, sites, networks)
95- Batch operations when possible
96- Implement exponential backoff for 429 errors
97- Use configurable rate limits via `UNIFI_RATE_LIMIT` environment variable
98- Log rate limit warnings for monitoring
99 
100## API Error Handling
101 
102Handle UniFi API-specific errors gracefully:
103 
104```python
105import httpx
106from typing import Dict, Any
107 
108class UniFiAPIError(Exception):
109    """Base exception for UniFi API errors."""
110    pass
111 
112class UniFiAuthenticationError(UniFiAPIError):
113    """Authentication failed - invalid API key."""
114    pass
115 
116class UniFiRateLimitError(UniFiAPIError):
117    """Rate limit exceeded."""
118    pass
119 
120async def safe_api_request(
121    client: httpx.AsyncClient,
122    method: str,
123    endpoint: str,
124    **kwargs
125) -> Dict[str, Any]:
126    """
127    Make a safe API request with proper error handling.
128 
129    Args:
130        client: HTTP client
131        method: HTTP method (GET, POST, etc.)
132        endpoint: API endpoint
133        **kwargs: Additional request parameters
134 
135    Returns:
136        Response data as dictionary
137 
138    Raises:
139        UniFiAuthenticationError: Invalid API key
140        UniFiRateLimitError: Rate limit exceeded
141        UniFiAPIError: Other API errors
142    """
143    try:
144        response = await client.request(method, endpoint, **kwargs)
145        response.raise_for_status()
146        return response.json()
147 
148    except httpx.HTTPStatusError as e:
149        if e.response.status_code == 401:
150            raise UniFiAuthenticationError(
151                "Invalid API key. Please check your UNIFI_API_KEY."
152            )
153        elif e.response.status_code == 429:
154            retry_after = e.response.headers.get("Retry-After", 60)
155            raise UniFiRateLimitError(
156                f"Rate limit exceeded. Retry after {retry_after} seconds."
157            )
158        else:
159            raise UniFiAPIError(f"API error: {e.response.status_code}")
160 
161    except httpx.RequestError as e:
162        raise UniFiAPIError(f"Request failed: {str(e)}")
163```
164 
165## Centralize API Calls
166 
167Keep all API interactions in dedicated modules:
168 
169```python
170# src/api/client.py
171class UniFiClient:
172    async def request(
173        self,
174        method: str,
175        endpoint: str,
176        **kwargs
177    ) -> Dict[str, Any]:
178        """
179        Make authenticated request to UniFi API.
180 
181        Handles authentication, retries, and error handling.
182        """
183        # Centralized implementation
184        pass
185```
186 
187## Official API Documentation
188 
189Always reference the official UniFi API documentation:
190 
191- **Getting Started**: https://developer.ui.com/site-manager-api/gettingstarted
192- **Project Reference**: `docs/UNIFI_API.md` (comprehensive guide)
193- **API Tutorial**: https://www.makewithdata.tech/p/build-a-mcp-server-for-ai-access
194