api-design

Files (1)

• SKILL.md

SKILL.md (first lines)

# API Design

## REST Conventions

### Resource Naming
```
GET    /users              → list users
POST   /users              → create user
GET    /users/:id          → get user
PUT    /users/:id          → replace user
PATCH  /users/:id          → update user
DELETE /users/:id          → delete user
GET    /users/:id/posts    → list user's posts
```

### HTTP Status Codes
| Code | Use |
|------|-----|
| 200 | Success |
| 201 | Created |
| 204 | No Content (delete success) |
| 400 | Bad Request (validation error) |
| 401 | Unauthorized (no/invalid auth) |
| 403 | Forbidden (insufficient permissions) |
| 404 | Not Found |
| 409 | Conflict (duplicate, version mismatch) |
| 422 | Unprocessable Entity (business logic error) |
| 429 | Too Many Requests |
| 500 | Internal Server Error |

### Response Envelope
```json
{
  "data": { "id": 1, "name": "Alice" },
  "meta": { "requestId": "abc-123" }
}
```

### Error Response
```json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input",
    "details": [
      { "field": "email", "message": "must be a valid email" }
    ]
  }
}
```

## Pagination

### Cursor-Based (Recommended)
```json
{
  "data": [...],
  "pagination": {
    "next_cursor": "eyJpZCI6MTAwfQ==",
    "has_more": true
  }
}
```
Request: `GET /users?cursor=eyJpZCI6MTAwfQ==&limit=20`

### Offset-Based
```json
{
  "data": [...],
  "pagination": {
    "total": 150,
    "page": 2,
    "per_page": 20
  }
}
```
Request: `GET /users?page=2&per_page=20`

## Filtering and Sorting

```
GET /users?status=active&role=admin&sort=-created_at,name
GET /users?filter[status]=active&filter[role]=admin
GET /posts?search=hello&fields=id,title,createdAt
```

## Versioning

### URL Path (Recommended)
```
/v1/users
/v2/users
```

### Header
```
Accept: application/vnd.myapi.v2+json
```

## Rate Limiting

Headers to include:
```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640000000
Retry-After: 30
```

## Authentication Patterns

### API Key
```
Authorization: Bearer sk_live_abc123
```

### OAuth2 Flow
```
POST /oauth/token

From ProjectZeroDays/FreeAI_AI_Inference_Workstation, MIT.

More from ProjectZeroDays/FreeAI_AI_Inference_Workstation