mirror of
https://github.com/lintsinghua/DeepAudit.git
synced 2026-11-22 05:07:12 +08:00
511 lines
11 KiB
Markdown
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)
|