@orchestrator-claude/definitions 3.5.0

package/kb/rest-conventions.md

@@ -0,0 +1,458 @@
+---
+title: "REST API Conventions"
+category: "patterns"
+tier: "foundational"
+tags: ["api", "rest", "http", "express"]
+template: "api"
+---
+
+# REST API Conventions
+
+## Overview
+
+This document defines REST API conventions and best practices for building consistent, maintainable, and scalable HTTP APIs using Express.js and Clean Architecture.
+
+**Project**: my-project
+**Template**: api
+
+---
+
+## 1. HTTP Methods
+
+### Standard Methods
+
+| Method | Purpose | Idempotent | Safe | Success Code |
+|--------|---------|------------|------|--------------|
+| GET | Retrieve resource(s) | Yes | Yes | 200, 404 |
+| POST | Create resource | No | No | 201, 400 |
+| PUT | Replace entire resource | Yes | No | 200, 404 |
+| PATCH | Partial update | No | No | 200, 404 |
+| DELETE | Remove resource | Yes | No | 204, 404 |
+
+### Best Practices
+
+1. **GET**: Never modify state, only retrieve data
+2. **POST**: Use for creation or non-idempotent operations
+3. **PUT**: Requires full resource representation
+4. **PATCH**: Use for partial updates
+5. **DELETE**: Return 204 No Content on success
+
+### Examples
+
+```typescript
+// GET - Retrieve resource
+router.get('/api/v1/users/:id', async (req, res) => {
+  const userId = req.params.id;
+  const result = await getUserUseCase.execute({ userId });
+
+  if (result.isErr()) {
+    return res.status(404).json({ error: 'User not found' });
+  }
+
+  res.status(200).json(result.value);
+});
+
+// POST - Create resource
+router.post('/api/v1/users', async (req, res) => {
+  const result = await createUserUseCase.execute(req.body);
+
+  if (result.isErr()) {
+    return res.status(400).json({ error: result.error });
+  }
+
+  res.status(201).json(result.value);
+});
+
+// DELETE - Remove resource
+router.delete('/api/v1/users/:id', async (req, res) => {
+  const userId = req.params.id;
+  const result = await deleteUserUseCase.execute({ userId });
+
+  if (result.isErr()) {
+    return res.status(404).json({ error: 'User not found' });
+  }
+
+  res.status(204).send();
+});
+```
+
+---
+
+## 2. URL Structure
+
+### Conventions
+
+1. **Use nouns, not verbs**
+   - ✅ `/users` `/orders` `/products`
+   - ❌ `/getUsers` `/createOrder` `/deleteProduct`
+
+2. **Use plural names**
+   - ✅ `/users` `/orders`
+   - ❌ `/user` `/order`
+
+3. **Use kebab-case for multi-word resources**
+   - ✅ `/order-items` `/user-profiles`
+   - ❌ `/orderItems` `/userProfiles`
+
+4. **Hierarchical structure for relationships**
+   - ✅ `/users/:userId/orders`
+   - ✅ `/posts/:postId/comments`
+
+5. **Always include API versioning**
+   - ✅ `/api/v1/users`
+   - ❌ `/api/users`
+
+### Examples
+
+```
+# Resource Collection
+GET    /api/v1/users              # List users
+POST   /api/v1/users              # Create user
+
+# Single Resource
+GET    /api/v1/users/:id          # Get user
+PUT    /api/v1/users/:id          # Replace user
+PATCH  /api/v1/users/:id          # Update user
+DELETE /api/v1/users/:id          # Delete user
+
+# Nested Resources
+GET    /api/v1/users/:id/orders   # List user's orders
+POST   /api/v1/users/:id/orders   # Create order for user
+
+# Filtering & Pagination (query params)
+GET    /api/v1/users?role=admin&page=2&limit=20
+GET    /api/v1/users?sort=name&order=asc
+```
+
+---
+
+## 3. HTTP Status Codes
+
+### Success Codes (2xx)
+
+| Code | Name | Usage |
+|------|------|-------|
+| 200 | OK | Successful GET, PUT, PATCH |
+| 201 | Created | Successful POST (resource created) |
+| 204 | No Content | Successful DELETE |
+
+### Client Error Codes (4xx)
+
+| Code | Name | Usage |
+|------|------|-------|
+| 400 | Bad Request | Invalid request payload |
+| 401 | Unauthorized | Missing or invalid auth |
+| 403 | Forbidden | Not authorized |
+| 404 | Not Found | Resource doesn't exist |
+| 409 | Conflict | Resource conflict (duplicate) |
+| 422 | Unprocessable Entity | Validation errors |
+| 429 | Too Many Requests | Rate limit exceeded |
+
+### Server Error Codes (5xx)
+
+| Code | Name | Usage |
+|------|------|-------|
+| 500 | Internal Server Error | Unexpected error |
+| 503 | Service Unavailable | Service down/maintenance |
+
+### Examples
+
+```typescript
+// 200 OK - Successful retrieval
+res.status(200).json({ user });
+
+// 201 Created - Resource created
+res.status(201).json({ user, id: newUserId });
+
+// 204 No Content - Successful deletion
+res.status(204).send();
+
+// 400 Bad Request - Invalid input
+res.status(400).json({ error: 'Invalid email format' });
+
+// 401 Unauthorized - Missing auth
+res.status(401).json({ error: 'Authentication required' });
+
+// 404 Not Found - Resource doesn't exist
+res.status(404).json({ error: 'User not found' });
+
+// 422 Unprocessable Entity - Validation errors
+res.status(422).json({
+  error: 'Validation failed',
+  details: validationErrors
+});
+```
+
+---
+
+## 4. Request/Response Headers
+
+### Standard Request Headers
+
+```http
+Content-Type: application/json
+Accept: application/json
+Authorization: Bearer <token>
+X-Request-Id: <uuid>
+```
+
+### Standard Response Headers
+
+```http
+Content-Type: application/json
+X-Request-Id: <uuid>
+Cache-Control: public, max-age=3600
+ETag: "33a64df551425fcc55e4d42a148795d9f25f89d4"
+```
+
+### Example Implementation
+
+```typescript
+// Request ID middleware
+app.use((req, res, next) => {
+  req.id = crypto.randomUUID();
+  res.setHeader('X-Request-Id', req.id);
+  next();
+});
+
+// Cache control for GET endpoints
+router.get('/api/v1/users', (req, res) => {
+  res.setHeader('Cache-Control', 'public, max-age=300');
+  res.json(users);
+});
+```
+
+---
+
+## 5. Pagination
+
+### Standard Query Parameters
+
+- `page` - Page number (1-indexed)
+- `limit` - Items per page (default: 20, max: 100)
+- `sort` - Sort field
+- `order` - Sort order (asc/desc)
+
+### Response Format
+
+```json
+{
+  "data": [...],
+  "meta": {
+    "page": 1,
+    "limit": 20,
+    "total": 150,
+    "totalPages": 8
+  },
+  "links": {
+    "self": "/api/v1/users?page=1&limit=20",
+    "first": "/api/v1/users?page=1&limit=20",
+    "prev": null,
+    "next": "/api/v1/users?page=2&limit=20",
+    "last": "/api/v1/users?page=8&limit=20"
+  }
+}
+```
+
+### Example Implementation
+
+```typescript
+router.get('/api/v1/users', async (req, res) => {
+  const page = parseInt(req.query.page as string) || 1;
+  const limit = Math.min(parseInt(req.query.limit as string) || 20, 100);
+
+  const result = await listUsersUseCase.execute({ page, limit });
+
+  if (result.isErr()) {
+    return res.status(500).json({ error: result.error });
+  }
+
+  const { users, total } = result.value;
+  const totalPages = Math.ceil(total / limit);
+
+  res.json({
+    data: users,
+    meta: { page, limit, total, totalPages },
+    links: {
+      self: `/api/v1/users?page=${page}&limit=${limit}`,
+      first: `/api/v1/users?page=1&limit=${limit}`,
+      prev: page > 1 ? `/api/v1/users?page=${page - 1}&limit=${limit}` : null,
+      next: page < totalPages ? `/api/v1/users?page=${page + 1}&limit=${limit}` : null,
+      last: `/api/v1/users?page=${totalPages}&limit=${limit}`,
+    },
+  });
+});
+```
+
+---
+
+## 6. Filtering & Sorting
+
+### Query Parameter Conventions
+
+```
+# Filter by field
+GET /api/v1/users?role=admin
+GET /api/v1/users?status=active
+
+# Multiple filters (AND)
+GET /api/v1/users?role=admin&status=active
+
+# Sort
+GET /api/v1/users?sort=name&order=asc
+GET /api/v1/users?sort=createdAt&order=desc
+```
+
+### Example Implementation
+
+```typescript
+router.get('/api/v1/users', async (req, res) => {
+  const filters = {
+    role: req.query.role as string,
+    status: req.query.status as string,
+  };
+
+  const sorting = {
+    field: (req.query.sort as string) || 'createdAt',
+    order: (req.query.order as 'asc' | 'desc') || 'desc',
+  };
+
+  const result = await listUsersUseCase.execute({ filters, sorting });
+  res.json(result.value);
+});
+```
+
+---
+
+## 7. HATEOAS (Hypermedia)
+
+### Basic Link Format
+
+```json
+{
+  "id": "123",
+  "name": "John Doe",
+  "links": {
+    "self": "/api/v1/users/123",
+    "orders": "/api/v1/users/123/orders",
+    "profile": "/api/v1/users/123/profile"
+  }
+}
+```
+
+### Example Implementation
+
+```typescript
+function addLinks(user: User, baseUrl: string) {
+  return {
+    ...user,
+    links: {
+      self: `${baseUrl}/api/v1/users/${user.id}`,
+      orders: `${baseUrl}/api/v1/users/${user.id}/orders`,
+      profile: `${baseUrl}/api/v1/users/${user.id}/profile`,
+    },
+  };
+}
+```
+
+---
+
+## 8. Content Negotiation
+
+### Accept Header
+
+```http
+Accept: application/json
+Accept: application/xml
+Accept: text/csv
+```
+
+### Example Implementation
+
+```typescript
+router.get('/api/v1/users/:id', async (req, res) => {
+  const result = await getUserUseCase.execute({ userId: req.params.id });
+
+  if (result.isErr()) {
+    return res.status(404).json({ error: 'User not found' });
+  }
+
+  const user = result.value;
+
+  // Content negotiation
+  if (req.accepts('json')) {
+    return res.json(user);
+  }
+
+  if (req.accepts('xml')) {
+    return res.type('xml').send(convertToXML(user));
+  }
+
+  res.status(406).json({ error: 'Not Acceptable' });
+});
+```
+
+---
+
+## 9. Versioning Strategies
+
+### URL Versioning (Recommended)
+
+```
+/api/v1/users
+/api/v2/users
+```
+
+**Pros**: Simple, explicit, cacheable
+**Cons**: URL changes between versions
+
+### Header Versioning
+
+```http
+Accept: application/vnd.myapi.v1+json
+```
+
+**Pros**: Clean URLs
+**Cons**: Less visible, harder to test
+
+---
+
+## 10. Testing REST APIs
+
+### Use Supertest
+
+```typescript
+import request from 'supertest';
+import { app } from '../src/server';
+
+describe('GET /api/v1/users/:id', () => {
+  it('should return user when found', async () => {
+    const response = await request(app)
+      .get('/api/v1/users/123')
+      .expect(200)
+      .expect('Content-Type', /json/);
+
+    expect(response.body).toHaveProperty('id', '123');
+  });
+
+  it('should return 404 when user not found', async () => {
+    await request(app)
+      .get('/api/v1/users/999')
+      .expect(404);
+  });
+});
+```
+
+---
+
+## References
+
+- [REST API Design Best Practices](https://restfulapi.net/)
+- [HTTP Status Codes (MDN)](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status)
+- [Roy Fielding's Dissertation on REST](https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm)
+
+---
+
+**Generated for**: my-project
+**Template**: api
+**Constitution Preset**: orchestrator