---
# API Patterns Guide

## Overview

<!-- 
GENERATION INSTRUCTIONS:
1. Scan codebase for API routes, controllers, middleware
2. Extract ACTUAL patterns used (don't invent)
3. Fill each section with REAL file paths and code
4. Keep examples minimal (5-15 lines, one per pattern)
5. Final output: 150-300 lines
-->

**Project**: [Extract from package.json/config]
**Stack**: [Detect framework, language, auth library]
**Base URL**: [Find in config/env]

---

## File Structure

<!-- Find and document where API code lives -->

| Purpose | Path |
|---------|------|
| Routes/Endpoints | `[scan for router files]` |
| Controllers/Handlers | `[scan for controller pattern]` |
| Middleware | `[scan for middleware folder]` |
| Validation | `[scan for validators/schemas]` |
| Models/Types | `[scan for models/entities]` |

---

## Endpoint Pattern

<!-- Extract ONE canonical endpoint showing the full pattern -->

```[detected_language]
// Source: [actual_file:lines]
[extract representative endpoint - prefer one with auth + validation]
```

**To add new endpoint, replicate this structure:**
1. Define route in `[routes_file]`
2. Add handler in `[controllers_path]`
3. Add validation in `[validators_path]` (if needed)

---

## Validation Pattern

<!-- Find how this codebase validates requests -->

**Approach**: [Detect: Zod/Joi/Yup/Pydantic/class-validator/custom]

```[lang]
// Source: [actual_file:lines]
[extract one validation schema example]
```

**Usage:**
```[lang]
// How validation is applied to routes
[extract middleware/decorator usage]
```

---

## Authentication

<!-- Find auth middleware/guards -->

**Method**: [Detect: JWT/Session/API Key/OAuth]

```[lang]
// Source: [actual_file:lines]
[extract auth middleware]
```

**Protect route:** `[extract exact syntax used]`
**Access user:** `[extract how user object is accessed]`

---

## Response Patterns

<!-- Find consistent response structures -->

**Success format:**
```json
[extract actual success response structure from code]
```

**Error format:**
```json
[extract actual error response structure from code]
```

**Helper/Utility** (if exists): `[path to response helpers]`

---

## Status Codes

<!-- Extract from actual handlers OR document conventions found -->

| Operation | Success | Common Errors |
|-----------|---------|---------------|
| Create | [find in POST handlers] | [find error codes] |
| Read | [find in GET handlers] | [find error codes] |
| Update | [find in PUT/PATCH] | [find error codes] |
| Delete | [find in DELETE] | [find error codes] |

---

## Error Handling

<!-- Find centralized error handling -->

```[lang]
// Source: [actual_file:lines]
[extract error handler/middleware or throwing pattern]
```

**Throw errors using:** `[extract exact syntax]`

---

## Pagination

<!-- Find if pagination exists, extract pattern -->

```[lang]
// Source: [actual_file:lines]
[extract pagination implementation]
```

**Params**: [extract actual query param names used]
**Defaults**: page=`[find]`, limit=`[find]`

---

## Conventions

<!-- Extract by analyzing multiple endpoints -->

| Aspect | Convention Used |
|--------|-----------------|
| Route naming | `[kebab-case/camelCase/snake_case]` |
| Controller methods | `[naming pattern found]` |
| Async handling | `[async/await, promises, try/catch wrapper]` |
| ID parameter | `[id/:id/uuid format]` |

---

## Anti-Patterns

<!-- Document what NOT to do based on codebase patterns -->

| ❌ Avoid | ✅ Use Instead | Reason |
|----------|----------------|--------|
| [detect inconsistencies or deprecated patterns] | [correct pattern from code] | [why] |

---

## Quick Reference

<!-- Condensed lookup table -->

| Task | Syntax | Example |
|------|--------|---------|
| Define route | `[extract]` | `[file:line]` |
| Add validation | `[extract]` | `[file:line]` |
| Protect route | `[extract]` | `[file:line]` |
| Return success | `[extract]` | `[file:line]` |
| Throw error | `[extract]` | `[file:line]` |

---