Add comprehensive documentation wiki for Docs Drift Guard

docs/wiki/API-Endpoints.md

@@ -0,0 +1,313 @@
+# API Endpoints
+
+The DataStack Platform API powers an internal employee management platform used by the HR Portal, Mobile App, Payroll Service, and Analytics Dashboard.
+
+All endpoints are versioned under `/v1` to support graceful deprecation.
+
+---
+
+## Base URL
+
+```
+http://localhost:8000
+```
+
+---
+
+## Interactive Documentation
+
+When the server is running, interactive docs are available at:
+
+| URL | Format |
+|-----|--------|
+| `http://localhost:8000/docs` | Swagger UI (interactive) |
+| `http://localhost:8000/redoc` | ReDoc (read-only) |
+| `http://localhost:8000/openapi.json` | Raw OpenAPI spec (JSON) |
+
+---
+
+## Endpoints Overview
+
+| Method | Path | Summary | Tag |
+|--------|------|---------|-----|
+| GET | `/health` | Health check | ops |
+| GET | `/v1/employees` | List employees | employees |
+| POST | `/v1/employees` | Onboard a new employee | employees |
+| GET | `/v1/employees/{employee_id}` | Get an employee by ID | employees |
+| PATCH | `/v1/employees/{employee_id}` | Update an employee | employees |
+| GET | `/v1/audit` | View API call mismatch audit log | ops |
+| DELETE | `/v1/audit` | Clear the audit log | ops |
+
+---
+
+## Health Check
+
+### `GET /health`
+
+Returns the current health status of the service.
+
+**Response (200):**
+```json
+{
+  "status": "ok",
+  "version": "1.0.0"
+}
+```
+
+**Example:**
+```bash
+curl -s http://localhost:8000/health | python -m json.tool
+```
+
+---
+
+## Employee Endpoints
+
+### `GET /v1/employees` -- List Employees
+
+List all employees, optionally filtered by department or status. Used by the HR Portal for the employee directory and by the Analytics Dashboard for headcount reporting.
+
+**Query Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `department` | string | No | Filter by department (e.g., "Engineering", "Sales", "HR") |
+| `status` | string | No | Filter by status: `active`, `on_leave`, `terminated` |
+
+**Response (200):**
+```json
+{
+  "total": 5,
+  "employees": [
+    {
+      "id": 1,
+      "first_name": "Sarah",
+      "last_name": "Chen",
+      "email": "sarah.chen@datastack.com",
+      "department": "Engineering",
+      "title": "Senior Backend Engineer",
+      "role": "member",
+      "status": "active",
+      "hired_at": "2022-03-15T00:00:00Z",
+      "bio": null
+    }
+  ]
+}
+```
+
+**Examples:**
+```bash
+# List all employees
+curl -s http://localhost:8000/v1/employees | python -m json.tool
+
+# Filter by department
+curl -s "http://localhost:8000/v1/employees?department=Engineering" | python -m json.tool
+
+# Filter by status
+curl -s "http://localhost:8000/v1/employees?status=on_leave" | python -m json.tool
+```
+
+---
+
+### `POST /v1/employees` -- Onboard a New Employee
+
+Create a new employee record during onboarding. Called by the HR Portal when a new hire accepts their offer.
+
+**Request Body:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `first_name` | string | Yes | Employee first name |
+| `last_name` | string | Yes | Employee last name |
+| `email` | string | Yes | Corporate email address |
+| `department` | string | Yes | Department (e.g., Engineering, Sales, HR) |
+| `title` | string | Yes | Job title |
+| `role` | string | No | Access role: `member` (default), `manager`, `admin` |
+
+**Response (201):**
+```json
+{
+  "id": 6,
+  "first_name": "Alex",
+  "last_name": "Rivera",
+  "email": "alex.rivera@datastack.com",
+  "department": "Product",
+  "title": "Product Manager",
+  "role": "member",
+  "status": "active",
+  "hired_at": "2026-02-24T02:00:00+00:00",
+  "bio": null
+}
+```
+
+**Example:**
+```bash
+curl -s -X POST http://localhost:8000/v1/employees \
+  -H "Content-Type: application/json" \
+  -d '{
+    "first_name": "Alex",
+    "last_name": "Rivera",
+    "email": "alex.rivera@datastack.com",
+    "department": "Product",
+    "title": "Product Manager"
+  }' | python -m json.tool
+```
+
+**Error (422):** Returned when required fields are missing or invalid.
+
+---
+
+### `GET /v1/employees/{employee_id}` -- Get Employee by ID
+
+Retrieve a single employee by their unique ID. Used by the Mobile App for the profile screen and by the Payroll Service to look up employee details.
+
+**Path Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `employee_id` | integer | Yes | Unique employee identifier |
+
+**Response (200):**
+```json
+{
+  "id": 1,
+  "first_name": "Sarah",
+  "last_name": "Chen",
+  "email": "sarah.chen@datastack.com",
+  "department": "Engineering",
+  "title": "Senior Backend Engineer",
+  "role": "member",
+  "status": "active",
+  "hired_at": "2022-03-15T00:00:00Z",
+  "bio": null
+}
+```
+
+**Error (404):** Returned when the employee ID does not exist.
+
+**Example:**
+```bash
+curl -s http://localhost:8000/v1/employees/1 | python -m json.tool
+```
+
+---
+
+### `PATCH /v1/employees/{employee_id}` -- Update Employee
+
+Update an employee's fields (partial update). Used by the HR Portal to change titles, departments, or status (e.g., when someone goes on leave or gets promoted).
+
+**Path Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `employee_id` | integer | Yes | Unique employee identifier |
+
+**Request Body (partial -- only include fields to update):**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `first_name` | string | Employee first name |
+| `last_name` | string | Employee last name |
+| `email` | string | Corporate email address |
+| `department` | string | Department |
+| `title` | string | Job title |
+| `role` | string | Access role: `member`, `manager`, `admin` |
+| `status` | string | Employment status: `active`, `on_leave`, `terminated` |
+
+**Response (200):** Returns the full updated employee object.
+
+**Error (404):** Returned when the employee ID does not exist.
+
+**Examples:**
+```bash
+# Promote an employee
+curl -s -X PATCH http://localhost:8000/v1/employees/3 \
+  -H "Content-Type: application/json" \
+  -d '{"title": "Senior Account Executive", "role": "manager"}' | python -m json.tool
+
+# Put employee on leave
+curl -s -X PATCH http://localhost:8000/v1/employees/1 \
+  -H "Content-Type: application/json" \
+  -d '{"status": "on_leave"}' | python -m json.tool
+```
+
+---
+
+## Audit Endpoints
+
+### `GET /v1/audit` -- View Audit Log
+
+Return all API call mismatches recorded by the middleware. Used by the platform team to identify clients using stale field names or calling nonexistent endpoints.
+
+**Response (200):**
+```json
+{
+  "total_mismatches": 2,
+  "entries": [
+    {
+      "timestamp": 1708000000.0,
+      "method": "POST",
+      "path": "/v1/employees",
+      "issue_type": "unknown_field",
+      "details": "Client sent field `username` but the schema only expects: ...",
+      "client_ip": "127.0.0.1"
+    }
+  ]
+}
+```
+
+**Example:**
+```bash
+curl -s http://localhost:8000/v1/audit | python -m json.tool
+```
+
+---
+
+### `DELETE /v1/audit` -- Clear Audit Log
+
+Clear all recorded mismatches.
+
+**Response (200):**
+```json
+{
+  "status": "cleared"
+}
+```
+
+**Example:**
+```bash
+curl -s -X DELETE http://localhost:8000/v1/audit | python -m json.tool
+```
+
+---
+
+## Seed Data
+
+The API starts with 5 pre-loaded employees:
+
+| ID | Name | Department | Title | Role | Status |
+|----|------|------------|-------|------|--------|
+| 1 | Sarah Chen | Engineering | Senior Backend Engineer | member | active |
+| 2 | Marcus Johnson | Engineering | Engineering Manager | manager | active |
+| 3 | Priya Patel | Sales | Account Executive | member | active |
+| 4 | James Wright | HR | HR Business Partner | admin | active |
+| 5 | Lisa Kim | Engineering | Frontend Engineer | member | on_leave |
+
+The in-memory store resets every time the server restarts.
+
+---
+
+## Authentication
+
+No authentication is currently required. JWT auth is planned for a future release.
+
+---
+
+## Common Error Codes
+
+| Code | Meaning |
+|------|---------|
+| 200 | Success |
+| 201 | Created (new employee onboarded) |
+| 404 | Resource not found (bad employee ID, nonexistent endpoint) |
+| 422 | Validation error (missing required fields, wrong types) |