api-patterns · v5.0.0 · 2025-10-08 · sha256 a4517dbadede9c38

api-patterns v5.0.0A

Immutable. This exact content never changes and is served at /api/v1/blob/a4517dbadede9c38.

---
version: "5.0.0"
scope: ["typescript", "javascript"]
alwaysApply: true
description: "API endpoint patterns and request handling conventions"
lastUpdated: "2025-10-08"
dependencies: ["quality-standards", "database-patterns", "endpoint-routing", "bun-runtime"]
---
## 🔍 Code Searchability Patterns

### Find api-patterns Issues with ast-grep

```bash
# Find async function $NAME(request: Request, env: Env, requestId: string)
# Find return createJSONResponse($$$)
# Find return createErrorResponse($$$)
# Find generateRequestId()
# Find createLogger($$$)
ast-grep --pattern 'async function $NAME(request: Request, env: Env, requestId: string)' src/
ast-grep --pattern 'return createJSONResponse($$$)' src/
ast-grep --pattern 'return createErrorResponse($$$)' src/
ast-grep --pattern 'generateRequestId()' src/
ast-grep --pattern 'createLogger($$$)' src/
sg -p 'async' src/
sg -p 'return' src/
sg -p 'return' src/
sg -p 'generateRequestId()' src/
sg -p 'createLogger($$$)' src/
```

### api-patterns Discovery Commands

```bash
sg search "async function" src/api/
sg search "createJSONResponse" src/
sg search "generateRequestId" src/
sg search "createLogger" src/
```

### Search Examples

```bash
# Find all API endpoint handlers
sg search 'async' src/
# Find JSON response patterns
sg search 'return' src/
# Find request ID generation
sg search 'return' src/
# Find logging patterns
sg search 'generateRequestId()' src/
```
## Error Handling Patterns

### Using Error Classes

**Location:** `src/utils/error-handler.ts`

```typescript
import { Errors, createErrorResponse } from '../utils/error-handler';

// In endpoint handler
try {
  // Validation error
  if (!isValid) {
    throw Errors.validationError(['Field is required']);
  }
  
  // Not found
  if (!record) {
    throw Errors.notFound('Event');
  }
  
  // Database error
  if (queryFailed) {
    throw Errors.databaseError('Query failed: ' + error.message);
  }
  
  // Success response
  return new Response(JSON.stringify(data), {
    headers: { 'Content-Type': 'application/json' }
  });
  
} catch (error) {
  return createErrorResponse(error, requestId, url.pathname);
}
```

### Error Types

```typescript
// Client errors (4xx)
Errors.badRequest(message, details?)       // 400
Errors.unauthorized(message?)              // 401
Errors.forbidden(message?)                 // 403
Errors.notFound(resource?)                 // 404
Errors.validationError(errors[])           // 400
Errors.rateLimit(message?)                 // 429

// Server errors (5xx)
Errors.databaseError(message)              // 500
Errors.serviceUnavailable(message?)        // 503
Errors.timeout(message?)                   // 504
```

### Async Handler Wrapper

```typescript
import { asyncHandler } from '../utils/error-handler';

// Automatically catches and formats errors
export const myEndpoint = asyncHandler(async (request, env, ctx) => {
  // Your code here
  // Any thrown errors will be caught and formatted automatically
  return new Response(JSON.stringify(result));
});
```

---

## API Endpoint Patterns

### REST API Structure

**Location:** `src/api/routes.ts`

```typescript
import { generateRequestId, CORS_HEADERS, createOPTIONSResponse } from '../utils/request';

export async function handleAPIRoute(
  request: Request,
  env: Env,
  ctx: ExecutionContext
): Promise<Response> {
  const requestId = generateRequestId();
  const url = new URL(request.url);
  const path = url.pathname.replace('/api', '');

  // Handle OPTIONS preflight
  if (request.method === 'OPTIONS') {
    return createOPTIONSResponse();
  }

  try {
    // Route to endpoint
    switch (path) {
      case '/events':
        return await getEvents(request, env, requestId);
      // ... more routes
      default:
        throw Errors.notFound('API endpoint');
    }
  } catch (error) {
    return createErrorResponse(error, requestId, path);
  }
}
```

### Endpoint Handler Pattern

```typescript
import {
  normalizeD1Result,
  createJSONResponse,
  getQueryParamNumber
} from '../utils/request';
import { createLogger } from '../utils/logger';

async function getMyEndpoint(
  request: Request,
  env: Env,
  requestId: string
): Promise<Response> {
  const logger = createLogger(request);

  // 1. Validate environment
  validateEnv(env, ['ANALYTICS']);

  // 2. Validate input
  const validation = validateQueryParams(url, [
    Validators.agentID(),
    Validators.limit(500)
  ]);

  if (!validation.valid) {
    return validationErrorResponse(validation.errors, requestId);
  }

  const { agentID, limit } = validation.sanitized!;

  // 3. Query database
  const result = await env.ANALYTICS.prepare(`
    SELECT * FROM table WHERE aid = ? LIMIT ?
  `).bind(agentID, limit).all();

  const data = normalizeD1Result<MyType>(result);

  // 4. Log success
  logger.info('query_completed', {
    requestId,
    recordCount: data.length
  });

  // 5. Return response
  return createJSONResponse({
    data,
    total: data.length,
    requestId,
    timestamp: new Date().toISOString()
  });
}
```

---

## Response Patterns

### Success Response

```typescript
return new Response(JSON.stringify({
  // Your data
  events: [...],
  customers: [...],
  
  // Metadata (always include)
  requestId: requestId,
  timestamp: new Date().toISOString(),
  
  // Pagination (if applicable)
  total: total,
  limit: limit,
  offset: offset
}), {
  headers: {
    'Content-Type': 'application/json',
    'Access-Control-Allow-Origin': '*'
  }
});
```

### Error Response (Automatic)

When using `createErrorResponse()`, format is:

```json
{
  "error": "ERROR_CODE",
  "code": "ERROR_CODE",
  "message": "Human-readable message",
  "details": { /* optional */ },
  "requestId": "abc123",
  "timestamp": "2025-10-07T14:45:00.000Z",
  "path": "/api/endpoint"
}
```

---

## CORS Patterns

### Standard CORS Headers

```typescript
import { CORS_HEADERS, createOPTIONSResponse, createJSONResponse } from '../utils/request';

// Handle OPTIONS preflight
if (request.method === 'OPTIONS') {
  return createOPTIONSResponse();
}

// Include in all responses (automatic with createJSONResponse)
return createJSONResponse({ data });

// Or manually
return new Response(data, { headers: { ...CORS_HEADERS } });
```

---

## Request ID Tracking

### Generate and Use

```typescript
import { generateRequestId, getRequestId } from '../utils/request';
import { createLogger } from '../utils/logger';

// Generate at start of request
const requestId = generateRequestId();

// Or extract from headers
const requestId = getRequestId(request);

// Use structured logging
const logger = createLogger(request);
logger.info('request_received', { requestId });
logger.info('request_completed', { requestId });
logger.error('request_failed', { requestId }, error);

// Include in response (automatic with createJSONResponse)
return createJSONResponse({
  ...data,
  requestId
});

// Include in errors
return createErrorResponse('Error message', 500, 'ERROR_CODE', requestId);
```

---

## Database Query Patterns

### Type-safe D1 Queries

```typescript
import { normalizeD1Result } from '../utils/request';

// Query with type conversion
const result = await env.ANALYTICS.prepare(`
  SELECT eid, mt, ts
  FROM line_movements
  WHERE eid = ?
  LIMIT ?
`).bind(eventID, limit).all();

// Normalize results with proper typing
type Movement = {
  eid: string;
  mt: string;
  ts: string;
};

const movements = normalizeD1Result<Movement>(result);
```

### Parameterized Queries (Prevent SQL Injection)

```typescript
// ✅ CORRECT: Parameterized
const result = await env.ANALYTICS.prepare(`
  SELECT * FROM table WHERE id = ? AND type = ?
`).bind(id, type).all();

// ❌ WRONG: String interpolation
const result = await env.ANALYTICS.prepare(`
  SELECT * FROM table WHERE id = '${id}' AND type = '${type}'
`).all();
```

---

## Testing Patterns

### Testing Endpoints

```bash
# Local testing
bun run dev

# Test with curl
curl "http://localhost:8787/api/events?sport=NFL&limit=10"

# Test with validation error
curl "http://localhost:8787/api/events?limit=9999"
```

### Testing Validation

```typescript
import { validateInput, Validators } from './validation';

const result = validateInput({ agentID: 'test_123' }, [
  Validators.agentID(true)
]);

expect(result.valid).toBe(true);
expect(result.sanitized.agentID).toBe('test_123');
```

---

## Best Practices

### 1. Always Validate Input

```typescript
// Every endpoint should validate
const validation = validateQueryParams(url, [...]);
if (!validation.valid) {
  return validationErrorResponse(validation.errors, requestId);
}
```

### 2. Always Handle Errors

```typescript
// Use try-catch or asyncHandler
try {
  // Your code
} catch (error) {
  return createErrorResponse(error, requestId, path);
}
```

### 3. Always Include CORS

```typescript
import { CORS_HEADERS, createJSONResponse } from '../utils/request';

// Use createJSONResponse (includes CORS automatically)
return createJSONResponse({ data });

// Or manually
headers: { ...CORS_HEADERS }
```

### 4. Always Track Requests

```typescript
import { generateRequestId } from '../utils/request';

// Generate requestId at start
const requestId = generateRequestId();

// Include in response (automatic with createJSONResponse)
return createJSONResponse({ ...data, requestId });
```

### 5. Always Log Appropriately

```typescript
import { createLogger } from '../utils/logger';

const logger = createLogger(request);

// Start of request
logger.info('request_received', { method, path });

// Success
logger.info('query_completed', { recordCount: count });

// Error
logger.error('query_failed', { errorCode: error.code }, error);
```

---

## Related Documentation

- **[REST_API_REFERENCE.md](mdc:docs/REST_API_REFERENCE.md)** - Complete API reference
- **[API_ENHANCEMENT_SUMMARY.md](mdc:docs/API_ENHANCEMENT_SUMMARY.md)** - Enhancement overview
- **[error-handler.ts](mdc:src/utils/error-handler.ts)** - Error handling utilities
- **[validation.ts](mdc:src/utils/validation.ts)** - Validation utilities
- **[routes.ts](mdc:src/api/routes.ts)** - API route implementations

## Related Rules

- [Quality Standards](mdc:.cursor/rules/quality-standards.mdc) - Code quality standards ⭐ **NEW**
- [Endpoint Routing](mdc:.cursor/rules/endpoint-routing.mdc) - Endpoint patterns
- [Security Patterns](mdc:.cursor/rules/security-patterns.mdc) - Security considerations
- [Database Patterns](mdc:.cursor/rules/database-patterns.mdc) - Database query patterns
- [Cloudflare Workers](mdc:.cursor/rules/cloudflare-workers.mdc) - Workers-specific patterns

## Related Documentation

- [docs/QUALITY_STANDARDS.md](mdc:docs/QUALITY_STANDARDS.md) - Complete quality guide ⭐ **NEW**
- [src/shared/constants.ts](mdc:src/shared/constants.ts) - All constants ⭐ **NEW**
- [src/utils/request.ts](mdc:src/utils/request.ts) - Request utilities ⭐ **NEW**
- [src/utils/logger.ts](mdc:src/utils/logger.ts) - Logging utilities ⭐ **NEW**

---

**Status:** Production patterns established
**Last Updated:** 2025-10-08