Files
2025-11-01 23:46:29 +08:00

511 lines
11 KiB
Markdown

# API Usage Examples
This document provides practical examples for using the XCodeReviewer API.
## Authentication
### Register User
```bash
curl -X POST "http://localhost:8000/api/v1/auth/register" \
-H "Content-Type: application/json" \
-d '{
"email": "user@example.com",
"username": "newuser",
"password": "SecurePass123!",
"full_name": "John Doe"
}'
```
### Login
```bash
curl -X POST "http://localhost:8000/api/v1/auth/login" \
-H "Content-Type: application/json" \
-d '{
"username": "user@example.com",
"password": "SecurePass123!"
}'
```
Response:
```json
{
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGc...",
"refresh_token": "eyJ0eXAiOiJKV1QiLCJhbGc...",
"token_type": "bearer"
}
```
### Use Access Token
```bash
# Set token as variable
TOKEN="eyJ0eXAiOiJKV1QiLCJhbGc..."
# Make authenticated request
curl -X GET "http://localhost:8000/api/v1/users/me" \
-H "Authorization: Bearer $TOKEN"
```
## Agent Operations
### Chat with Agent
```bash
curl -X POST "http://localhost:8000/api/v1/agents/chat" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"message": "Review this Python code for security issues",
"code": "import os\npassword = os.getenv(\"PASSWORD\")\nquery = f\"SELECT * FROM users WHERE id = {user_id}\"",
"language": "python",
"agent_name": "security"
}'
```
### Analyze Code
```bash
curl -X POST "http://localhost:8000/api/v1/agents/analyze" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"code": "def calculate(a, b):\n return a / b",
"language": "python",
"analysis_type": "full"
}'
```
### Reset Agent Session
```bash
curl -X POST "http://localhost:8000/api/v1/agents/reset/security" \
-H "Authorization: Bearer $TOKEN"
```
## Data Migration
### Export User Data
```bash
curl -X POST "http://localhost:8000/api/v1/migration/export" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"include_projects": true,
"include_tasks": true,
"include_issues": true,
"include_settings": true
}' \
-o export.json
```
### Download Export
```bash
curl -X GET "http://localhost:8000/api/v1/migration/export/download" \
-H "Authorization: Bearer $TOKEN" \
-o "export_$(date +%Y%m%d).json"
```
### Validate Import Data
```bash
curl -X POST "http://localhost:8000/api/v1/migration/validate" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d @export.json
```
### Import Data
```bash
curl -X POST "http://localhost:8000/api/v1/migration/import" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d @export.json
```
### Upload and Import File
```bash
curl -X POST "http://localhost:8000/api/v1/migration/import/upload" \
-H "Authorization: Bearer $TOKEN" \
-F "file=@export.json" \
-F "skip_existing=true"
```
## Monitoring (Admin Only)
### System Health Check
```bash
curl -X GET "http://localhost:8000/api/v1/monitoring/health" \
-H "Authorization: Bearer $ADMIN_TOKEN"
```
### Database Pool Statistics
```bash
curl -X GET "http://localhost:8000/api/v1/monitoring/database/pool" \
-H "Authorization: Bearer $ADMIN_TOKEN"
```
### Redis Cache Statistics
```bash
curl -X GET "http://localhost:8000/api/v1/monitoring/redis/cache" \
-H "Authorization: Bearer $ADMIN_TOKEN"
```
### Clear Redis Cache
```bash
curl -X POST "http://localhost:8000/api/v1/monitoring/redis/cache/clear" \
-H "Authorization: Bearer $ADMIN_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"pattern": "cache:*"
}'
```
### Celery Workers
```bash
curl -X GET "http://localhost:8000/api/v1/monitoring/celery/workers" \
-H "Authorization: Bearer $ADMIN_TOKEN"
```
### Active Tasks
```bash
curl -X GET "http://localhost:8000/api/v1/monitoring/celery/tasks/active" \
-H "Authorization: Bearer $ADMIN_TOKEN"
```
### Revoke Task
```bash
curl -X POST "http://localhost:8000/api/v1/monitoring/celery/tasks/TASK_ID/revoke" \
-H "Authorization: Bearer $ADMIN_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"terminate": true
}'
```
### LLM Pool Statistics
```bash
curl -X GET "http://localhost:8000/api/v1/monitoring/llm/pools" \
-H "Authorization: Bearer $ADMIN_TOKEN"
```
### Specific Provider Stats
```bash
curl -X GET "http://localhost:8000/api/v1/monitoring/llm/pools/openai" \
-H "Authorization: Bearer $ADMIN_TOKEN"
```
## Python Client Examples
### Using requests
```python
import requests
# Base URL
BASE_URL = "http://localhost:8000/api/v1"
# Login
response = requests.post(
f"{BASE_URL}/auth/login",
json={
"username": "user@example.com",
"password": "SecurePass123!"
}
)
tokens = response.json()
access_token = tokens["access_token"]
# Set headers
headers = {
"Authorization": f"Bearer {access_token}",
"Content-Type": "application/json"
}
# Chat with agent
response = requests.post(
f"{BASE_URL}/agents/chat",
headers=headers,
json={
"message": "Review this code",
"code": "print('hello')",
"language": "python"
}
)
result = response.json()
print(result)
```
### Using httpx (async)
```python
import httpx
import asyncio
async def main():
async with httpx.AsyncClient() as client:
# Login
response = await client.post(
"http://localhost:8000/api/v1/auth/login",
json={
"username": "user@example.com",
"password": "SecurePass123!"
}
)
tokens = response.json()
# Set headers
headers = {
"Authorization": f"Bearer {tokens['access_token']}"
}
# Chat with agent
response = await client.post(
"http://localhost:8000/api/v1/agents/chat",
headers=headers,
json={
"message": "Review this code",
"code": "print('hello')",
"language": "python"
}
)
result = response.json()
print(result)
asyncio.run(main())
```
## JavaScript/TypeScript Examples
### Using fetch
```javascript
// Login
const loginResponse = await fetch('http://localhost:8000/api/v1/auth/login', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
},
body: JSON.stringify({
username: 'user@example.com',
password: 'SecurePass123!'
})
});
const { access_token } = await loginResponse.json();
// Chat with agent
const chatResponse = await fetch('http://localhost:8000/api/v1/agents/chat', {
method: 'POST',
headers: {
'Authorization': `Bearer ${access_token}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
message: 'Review this code',
code: "print('hello')",
language: 'python'
})
});
const result = await chatResponse.json();
console.log(result);
```
### Using axios
```javascript
import axios from 'axios';
const api = axios.create({
baseURL: 'http://localhost:8000/api/v1',
headers: {
'Content-Type': 'application/json',
}
});
// Login
const loginResponse = await api.post('/auth/login', {
username: 'user@example.com',
password: 'SecurePass123!'
});
const { access_token } = loginResponse.data;
// Set token for future requests
api.defaults.headers.common['Authorization'] = `Bearer ${access_token}`;
// Chat with agent
const chatResponse = await api.post('/agents/chat', {
message: 'Review this code',
code: "print('hello')",
language: 'python'
});
console.log(chatResponse.data);
```
## Error Handling
### Handle API Errors
```python
import requests
try:
response = requests.post(
"http://localhost:8000/api/v1/agents/chat",
headers=headers,
json=data
)
response.raise_for_status() # Raise exception for 4xx/5xx
result = response.json()
except requests.exceptions.HTTPError as e:
if e.response.status_code == 401:
print("Unauthorized - token expired or invalid")
elif e.response.status_code == 429:
print("Rate limit exceeded")
elif e.response.status_code == 500:
print("Server error")
else:
print(f"HTTP error: {e}")
except requests.exceptions.RequestException as e:
print(f"Request failed: {e}")
```
### Retry Logic
```python
from tenacity import retry, stop_after_attempt, wait_exponential
@retry(
stop=stop_after_attempt(3),
wait=wait_exponential(multiplier=1, min=2, max=10)
)
def call_api_with_retry():
response = requests.post(
"http://localhost:8000/api/v1/agents/chat",
headers=headers,
json=data
)
response.raise_for_status()
return response.json()
try:
result = call_api_with_retry()
except Exception as e:
print(f"Failed after retries: {e}")
```
## Rate Limiting
The API implements rate limiting:
- **Per minute**: 60 requests
- **Per hour**: 1000 requests
When rate limited, you'll receive a 429 response with `Retry-After` header.
```python
response = requests.get(url, headers=headers)
if response.status_code == 429:
retry_after = int(response.headers.get('Retry-After', 60))
print(f"Rate limited. Retry after {retry_after} seconds")
time.sleep(retry_after)
response = requests.get(url, headers=headers)
```
## Pagination
For endpoints that return lists:
```bash
curl -X GET "http://localhost:8000/api/v1/projects?skip=0&limit=10" \
-H "Authorization: Bearer $TOKEN"
```
```python
def get_all_projects(token):
projects = []
skip = 0
limit = 100
while True:
response = requests.get(
f"{BASE_URL}/projects",
headers={"Authorization": f"Bearer {token}"},
params={"skip": skip, "limit": limit}
)
batch = response.json()
if not batch:
break
projects.extend(batch)
skip += limit
return projects
```
## WebSocket (Future)
```javascript
// Connect to WebSocket for real-time updates
const ws = new WebSocket('ws://localhost:8000/ws');
ws.onopen = () => {
console.log('Connected');
ws.send(JSON.stringify({
type: 'auth',
token: access_token
}));
};
ws.onmessage = (event) => {
const data = JSON.parse(event.data);
console.log('Received:', data);
};
ws.onerror = (error) => {
console.error('WebSocket error:', error);
};
ws.onclose = () => {
console.log('Disconnected');
};
```
## Best Practices
1. **Always use HTTPS in production**
2. **Store tokens securely** (not in localStorage for sensitive apps)
3. **Implement token refresh** before expiration
4. **Handle rate limiting** gracefully
5. **Use connection pooling** for multiple requests
6. **Implement retry logic** with exponential backoff
7. **Validate responses** before using data
8. **Log errors** for debugging
9. **Use timeouts** to prevent hanging requests
10. **Monitor API usage** and performance
## References
- [API Documentation](http://localhost:8000/api/v1/docs)
- [Authentication Guide](authentication.md)
- [Error Codes](error-codes.md)
- [Rate Limiting](rate-limiting.md)