calypso/docs/alpha/sds/SDS-03-API-Design.md

# 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