tidy up documentation for alpha release
This commit is contained in:
Warp Agent
286
docs/alpha/sds/SDS-03-API-Design.md
Normal file
286
docs/alpha/sds/SDS-03-API-Design.md
Normal file
@@ -0,0 +1,286 @@
|
||||
# SDS-03: API Design
|
||||
|
||||
## 1. API Overview
|
||||
|
||||
### 1.1 API Style
|
||||
- **RESTful**: Resource-based API design
|
||||
- **Versioning**: `/api/v1/` prefix
|
||||
- **Content-Type**: `application/json`
|
||||
- **Authentication**: JWT Bearer tokens
|
||||
|
||||
### 1.2 API Base URL
|
||||
```
|
||||
http://localhost:8080/api/v1
|
||||
```
|
||||
|
||||
## 2. Authentication API
|
||||
|
||||
### 2.1 Endpoints
|
||||
```
|
||||
POST /auth/login
|
||||
POST /auth/logout
|
||||
GET /auth/me
|
||||
```
|
||||
|
||||
### 2.2 Request/Response Examples
|
||||
|
||||
#### Login
|
||||
```http
|
||||
POST /api/v1/auth/login
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"username": "admin",
|
||||
"password": "password"
|
||||
}
|
||||
|
||||
Response: 200 OK
|
||||
{
|
||||
"token": "eyJhbGciOiJIUzI1NiIs...",
|
||||
"user": {
|
||||
"id": "uuid",
|
||||
"username": "admin",
|
||||
"email": "admin@example.com",
|
||||
"roles": ["admin"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Get Current User
|
||||
```http
|
||||
GET /api/v1/auth/me
|
||||
Authorization: Bearer <token>
|
||||
|
||||
Response: 200 OK
|
||||
{
|
||||
"id": "uuid",
|
||||
"username": "admin",
|
||||
"email": "admin@example.com",
|
||||
"roles": ["admin"],
|
||||
"permissions": ["storage:read", "storage:write", ...]
|
||||
}
|
||||
```
|
||||
|
||||
## 3. Storage API
|
||||
|
||||
### 3.1 ZFS Pools
|
||||
```
|
||||
GET /storage/zfs/pools
|
||||
GET /storage/zfs/pools/:id
|
||||
POST /storage/zfs/pools
|
||||
DELETE /storage/zfs/pools/:id
|
||||
POST /storage/zfs/pools/:id/spare
|
||||
```
|
||||
|
||||
### 3.2 ZFS Datasets
|
||||
```
|
||||
GET /storage/zfs/pools/:id/datasets
|
||||
POST /storage/zfs/pools/:id/datasets
|
||||
DELETE /storage/zfs/pools/:id/datasets/:dataset
|
||||
```
|
||||
|
||||
### 3.3 Request/Response Examples
|
||||
|
||||
#### Create ZFS Pool
|
||||
```http
|
||||
POST /api/v1/storage/zfs/pools
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"name": "tank",
|
||||
"raid_level": "mirror",
|
||||
"disks": ["/dev/sdb", "/dev/sdc"],
|
||||
"compression": "lz4",
|
||||
"deduplication": false
|
||||
}
|
||||
|
||||
Response: 201 Created
|
||||
{
|
||||
"id": "uuid",
|
||||
"name": "tank",
|
||||
"status": "online",
|
||||
"total_capacity_bytes": 1000000000000,
|
||||
"created_at": "2025-01-01T00:00:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
## 4. Shares API
|
||||
|
||||
### 4.1 Endpoints
|
||||
```
|
||||
GET /shares
|
||||
GET /shares/:id
|
||||
POST /shares
|
||||
PUT /shares/:id
|
||||
DELETE /shares/:id
|
||||
```
|
||||
|
||||
### 4.2 Request/Response Examples
|
||||
|
||||
#### Create Share
|
||||
```http
|
||||
POST /api/v1/shares
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"dataset_id": "uuid",
|
||||
"share_type": "both",
|
||||
"nfs_enabled": true,
|
||||
"nfs_clients": ["192.168.1.0/24"],
|
||||
"smb_enabled": true,
|
||||
"smb_share_name": "shared",
|
||||
"smb_path": "/mnt/tank/shared",
|
||||
"smb_guest_ok": false,
|
||||
"smb_read_only": false
|
||||
}
|
||||
|
||||
Response: 201 Created
|
||||
{
|
||||
"id": "uuid",
|
||||
"dataset_id": "uuid",
|
||||
"share_type": "both",
|
||||
"nfs_enabled": true,
|
||||
"smb_enabled": true,
|
||||
"created_at": "2025-01-01T00:00:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
## 5. iSCSI API
|
||||
|
||||
### 5.1 Endpoints
|
||||
```
|
||||
GET /scst/targets
|
||||
GET /scst/targets/:id
|
||||
POST /scst/targets
|
||||
DELETE /scst/targets/:id
|
||||
POST /scst/targets/:id/luns
|
||||
DELETE /scst/targets/:id/luns/:lunId
|
||||
POST /scst/targets/:id/initiators
|
||||
GET /scst/initiators
|
||||
POST /scst/config/apply
|
||||
```
|
||||
|
||||
## 6. System API
|
||||
|
||||
### 6.1 Endpoints
|
||||
```
|
||||
GET /system/services
|
||||
GET /system/services/:name
|
||||
POST /system/services/:name/restart
|
||||
GET /system/services/:name/logs
|
||||
GET /system/interfaces
|
||||
PUT /system/interfaces/:name
|
||||
GET /system/ntp
|
||||
POST /system/ntp
|
||||
GET /system/logs
|
||||
GET /system/network/throughput
|
||||
POST /system/execute
|
||||
POST /system/support-bundle
|
||||
```
|
||||
|
||||
## 7. Monitoring API
|
||||
|
||||
### 7.1 Endpoints
|
||||
```
|
||||
GET /monitoring/metrics
|
||||
GET /monitoring/health
|
||||
GET /monitoring/alerts
|
||||
GET /monitoring/alerts/:id
|
||||
POST /monitoring/alerts/:id/acknowledge
|
||||
POST /monitoring/alerts/:id/resolve
|
||||
GET /monitoring/rules
|
||||
POST /monitoring/rules
|
||||
```
|
||||
|
||||
## 8. IAM API
|
||||
|
||||
### 8.1 Endpoints
|
||||
```
|
||||
GET /iam/users
|
||||
GET /iam/users/:id
|
||||
POST /iam/users
|
||||
PUT /iam/users/:id
|
||||
DELETE /iam/users/:id
|
||||
|
||||
GET /iam/roles
|
||||
GET /iam/roles/:id
|
||||
POST /iam/roles
|
||||
PUT /iam/roles/:id
|
||||
DELETE /iam/roles/:id
|
||||
|
||||
GET /iam/permissions
|
||||
GET /iam/groups
|
||||
```
|
||||
|
||||
## 9. Error Responses
|
||||
|
||||
### 9.1 Error Format
|
||||
```json
|
||||
{
|
||||
"error": "Error message",
|
||||
"code": "ERROR_CODE",
|
||||
"details": {
|
||||
"field": "validation error"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 9.2 HTTP Status Codes
|
||||
- **200 OK**: Success
|
||||
- **201 Created**: Resource created
|
||||
- **400 Bad Request**: Validation error
|
||||
- **401 Unauthorized**: Authentication required
|
||||
- **403 Forbidden**: Permission denied
|
||||
- **404 Not Found**: Resource not found
|
||||
- **500 Internal Server Error**: Server error
|
||||
|
||||
## 10. Pagination
|
||||
|
||||
### 10.1 Pagination Parameters
|
||||
```
|
||||
GET /api/v1/resource?page=1&limit=20
|
||||
```
|
||||
|
||||
### 10.2 Pagination Response
|
||||
```json
|
||||
{
|
||||
"data": [...],
|
||||
"pagination": {
|
||||
"page": 1,
|
||||
"limit": 20,
|
||||
"total": 100,
|
||||
"total_pages": 5
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 11. Filtering & Sorting
|
||||
|
||||
### 11.1 Filtering
|
||||
```
|
||||
GET /api/v1/resource?status=active&type=filesystem
|
||||
```
|
||||
|
||||
### 11.2 Sorting
|
||||
```
|
||||
GET /api/v1/resource?sort=name&order=asc
|
||||
```
|
||||
|
||||
## 12. Rate Limiting
|
||||
|
||||
### 12.1 Rate Limits
|
||||
- **Default**: 100 requests per minute per IP
|
||||
- **Authenticated**: 200 requests per minute per user
|
||||
- **Headers**: `X-RateLimit-Limit`, `X-RateLimit-Remaining`
|
||||
|
||||
## 13. Caching
|
||||
|
||||
### 13.1 Cache Headers
|
||||
- **Cache-Control**: `max-age=300` for GET requests
|
||||
- **ETag**: Entity tags for cache validation
|
||||
- **Last-Modified**: Last modification time
|
||||
|
||||
### 13.2 Cache Invalidation
|
||||
- **On Write**: Invalidate related cache entries
|
||||
- **Manual**: Clear cache via admin endpoint
|
||||
|
||||
Reference in New Issue
Block a user