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

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

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

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

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

{
  "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

{
  "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