# Resources as nouns
GET    /students         # List
GET    /students/123     # Read
POST   /students         # Create
PUT    /students/123     # Update
DELETE /students/123     # Delete

# Actions as sub-resources
POST   /students/123/swipe
POST   /schools/456/save

// Request
interface ApiRequest<T> {
  data: T;
  metadata?: {
    client_version: string;
    request_id: string;
  };
}

// Response
interface ApiResponse<T> {
  data?: T;
  error?: ApiError;
  metadata: {
    timestamp: string;
    version: string;
  };
}

interface ApiError {
  code: string;          // MACHINE_READABLE_CODE
  message: string;       // Human-friendly message
  details?: unknown;     // Additional context
  help_url?: string;     // Link to docs
}

// Middleware example
async function authenticate(req: Request) {
  const token = req.headers.get('Authorization')?.replace('Bearer ', '');
  
  if (!token) {
    throw new ApiError('UNAUTHORIZED', 'Missing token');
  }
  
  const { data: user, error } = await supabase.auth.getUser(token);
  
  if (error) {
    throw new ApiError('INVALID_TOKEN', 'Invalid or expired token');
  }
  
  return user;
}

# URL path versioning
/v1/students
/v2/students  # Breaking changes

# Header versioning for minor changes
X-API-Version: 2024-01-15

// Example Partner API structure
src/
├── routes/
│   ├── analytics.ts
│   ├── students.ts
│   └── messages.ts
├── middleware/
│   ├── auth.ts
│   ├── rateLimit.ts
│   └── logging.ts
├── services/
│   ├── supabase.ts
│   └── cache.ts
└── types/
    └── api.ts