stack/docs/4-api/1-conventions/1-endpoints.md

# API Endpoint Conventions

Standard patterns for all Mosaic Stack API endpoints.

## Base URL

- **Development:** `http://localhost:3001`
- **Production:** `https://api.example.com`

## Standard REST Endpoints

```
GET    /api/{resource}           # List resources (with pagination)
GET    /api/{resource}/:id       # Get single resource
POST   /api/{resource}           # Create new resource
PATCH  /api/{resource}/:id       # Update resource (partial)
PUT    /api/{resource}/:id       # Replace resource (full)
DELETE /api/{resource}/:id       # Delete resource
```

## Response Format

### Success Response

```json
{
  "data": {
    "id": "uuid",
    "name": "Example",
    "createdAt": "2026-01-28T12:00:00.000Z"
  }
}
```

### List Response (with pagination)

```json
{
  "data": [
    { "id": "1", "name": "Item 1" },
    { "id": "2", "name": "Item 2" }
  ],
  "meta": {
    "total": 50,
    "page": 1,
    "limit": 10,
    "totalPages": 5
  }
}
```

### Error Response

```json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input data",
    "details": {
      "email": "Invalid email format"
    }
  }
}
```

## HTTP Status Codes

| Code | Meaning | Usage |
|------|---------|-------|
| 200 | OK | Successful GET, PATCH, PUT |
| 201 | Created | Successful POST |
| 204 | No Content | Successful DELETE |
| 400 | Bad Request | Invalid input |
| 401 | Unauthorized | Missing/invalid auth token |
| 403 | Forbidden | Valid token, insufficient permissions |
| 404 | Not Found | Resource doesn't exist |
| 409 | Conflict | Resource already exists |
| 422 | Unprocessable Entity | Validation failed |
| 500 | Internal Server Error | Server error |

## Pagination

All list endpoints support pagination via query parameters:

```
GET /api/tasks?page=1&limit=20
```

**Parameters:**
- `page` — Page number (default: 1)
- `limit` — Items per page (default: 10, max: 100)

**Response includes:**
```json
{
  "data": [...],
  "meta": {
    "total": 150,
    "page": 1,
    "limit": 20,
    "totalPages": 8
  }
}
```

## Filtering

Use query parameters for filtering:

```
GET /api/tasks?status=active&priority=high
GET /api/events?start_date=2026-01-01&end_date=2026-01-31
```

**Supported operators:**
- `=` — Equals
- `_gt` — Greater than (e.g., `created_at_gt=2026-01-01`)
- `_lt` — Less than
- `_gte` — Greater than or equal
- `_lte` — Less than or equal
- `_in` — In array (e.g., `status_in=active,pending`)

## Sorting

Use `sort` parameter:

```
GET /api/tasks?sort=created_at           # Ascending
GET /api/tasks?sort=-created_at          # Descending (minus prefix)
GET /api/tasks?sort=-priority,created_at # Multiple fields
```

## Field Selection

Request specific fields to reduce payload size:

```
GET /api/tasks?fields=id,title,status
```

**Response:**
```json
{
  "data": [
    { "id": "1", "title": "Task 1", "status": "active" }
  ]
}
```

## Relationships

Include related resources:

```
GET /api/tasks?include=assignee,project
```

**Response:**
```json
{
  "data": {
    "id": "1",
    "title": "Task 1",
    "assignee": {
      "id": "user-1",
      "name": "John Doe"
    },
    "project": {
      "id": "proj-1",
      "name": "Project Alpha"
    }
  }
}
```

## Authentication

All authenticated endpoints require Bearer token:

```http
Authorization: Bearer {session_token}
```

See [Authentication Endpoints](../2-authentication/1-endpoints.md) for details.

## Request Headers

**Required:**
```http
Content-Type: application/json
```

**Optional:**
```http
Authorization: Bearer {token}
X-Workspace-ID: {workspace-uuid}  # For multi-tenant requests
```

## Validation Errors

Validation errors return 422 with detailed field errors:

```json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Input validation failed",
    "details": {
      "email": "Invalid email format",
      "password": "Must be at least 8 characters"
    }
  }
}
```

## Rate Limiting

API endpoints are rate-limited:

- **Anonymous:** 60 requests/hour
- **Authenticated:** 1000 requests/hour

**Rate limit headers:**
```http
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 950
X-RateLimit-Reset: 1643723400
```

When exceeded, returns 429 Too Many Requests.

## CORS

CORS is configured for frontend origin:

```javascript
// Allowed origins
const origins = [
  process.env.NEXT_PUBLIC_APP_URL,
  'http://localhost:3000',
  'http://localhost:3001'
];
```

## Versioning

Currently v1 (implicit). Future versions will use URL versioning:

```
/api/v2/tasks
```

## Health Check

```
GET /health
```

**Response:**
```json
{
  "status": "ok",
  "timestamp": "2026-01-28T12:00:00.000Z",
  "uptime": 123456
}
```

## Examples

### Create Task

```bash
curl -X POST http://localhost:3001/api/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {token}" \
  -d '{
    "title": "Complete API documentation",
    "description": "Write comprehensive API docs",
    "priority": "high",
    "targetDate": "2026-01-30"
  }'
```

**Response (201):**
```json
{
  "data": {
    "id": "task-uuid",
    "title": "Complete API documentation",
    "status": "pending",
    "priority": "high",
    "createdAt": "2026-01-28T12:00:00.000Z"
  }
}
```

### List Tasks with Filters

```bash
curl "http://localhost:3001/api/tasks?status=active&sort=-created_at&limit=5" \
  -H "Authorization: Bearer {token}"
```

### Update Task

```bash
curl -X PATCH http://localhost:3001/api/tasks/task-uuid \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {token}" \
  -d '{
    "status": "completed"
  }'
```

## Next Steps

- **Authentication** — [Authentication Endpoints](../2-authentication/1-endpoints.md)
- **Type Definitions** — [API Types](../2-authentication/2-types.md)
- **Implementation** — [Development Workflow](../../2-development/1-workflow/1-branching.md)