0e7097ed1b
First-attempt commit3a5c6e184only captured the .gitignore change; the pre-commit hook silently dropped the 343 staged moves/deletes during lint-staged's "no matching task" path. This commit re-applies the intended J1 content on top ofbec75f143(which was pushed in parallel). Uses --no-verify because: - J1 only touches .md/.json/.log/.png/binaries — zero code that would benefit from lint-staged, typecheck, or vitest - The hook demonstrated it corrupts pure-rename commits in this repo - Explicitly authorized by user for this one commit Changes (343 total: 169 deletions + 174 renames): Binaries purged (~167 MB): - veza-backend-api/{server,modern-server,encrypt_oauth_tokens,seed,seed-v2} Generated reports purged: - 9 apps/web/lint_report*.json (~32 MB) - 8 apps/web/tsc_*.{log,txt} + ts_*.log (TS error snapshots) - 3 apps/web/storybook_*.json (1375+ stored errors) - apps/web/{build_errors*,build_output,final_errors}.txt - 70 veza-backend-api/coverage*.out + coverage_groups/ (~4 MB) - 3 veza-backend-api/internal/handlers/*.bak Root cleanup: - 54 audit-*.png (visual regression baselines, ~11 MB) - 9 stale MVP-era scripts (Jan 27, hardcoded v0.101): start_{iteration,mvp,recovery}.sh, test_{mvp_endpoints,protected_endpoints,user_journey}.sh, validate_v0101.sh, verify_logs_setup.sh, gen_hash.py Session docs archived (not deleted — preserved under docs/archive/): - 78 apps/web/*.md → docs/archive/frontend-sessions-2026/ - 43 veza-backend-api/*.md → docs/archive/backend-sessions-2026/ - 53 docs/{RETROSPECTIVE_V,SMOKE_TEST_V,PLAN_V0_,V0_*_RELEASE_SCOPE, AUDIT_,PLAN_ACTION_AUDIT,REMEDIATION_PROGRESS}*.md → docs/archive/v0-history/ README.md and CONTRIBUTING.md preserved in apps/web/ and veza-backend-api/. Note: The .gitignore rules preventing recurrence were already pushed in3a5c6e184and remain in place — this commit does not modify .gitignore. Refs: AUDIT_REPORT.md §11
83 lines
2.1 KiB
Markdown
83 lines
2.1 KiB
Markdown
# Veza API Contract (Finalized)
|
|
|
|
## 1. Overview
|
|
This document defines the finalized API contract for the Veza backend. All endpoints adhere to strict JSON standards, snake_case naming conventions, and a unified response envelope.
|
|
|
|
## 2. Global Standards
|
|
- **Protocol**: HTTP/1.1
|
|
- **Content-Type**: `application/json`
|
|
- **Charset**: `utf-8`
|
|
- **Date Format**: ISO 8601 (`YYYY-MM-DDThh:mm:ssZ`)
|
|
- **Naming Convention**: `snake_case` for all JSON keys.
|
|
|
|
## 3. Response Envelope
|
|
Every API response (Success or Error) is wrapped in a unified envelope.
|
|
|
|
### 3.1. Success Response
|
|
HTTP Status: `200 OK`, `201 Created`
|
|
```json
|
|
{
|
|
"success": true,
|
|
"data": {
|
|
// Resource or Object
|
|
"id": "123",
|
|
"name": "example"
|
|
},
|
|
"error": null
|
|
}
|
|
```
|
|
|
|
### 3.2. Error Response
|
|
HTTP Status: `4xx`, `5xx`
|
|
```json
|
|
{
|
|
"success": false,
|
|
"data": null,
|
|
"error": {
|
|
"code": 400,
|
|
"message": "Validation failed",
|
|
"details": [
|
|
{
|
|
"field": "email",
|
|
"message": "Invalid email format"
|
|
}
|
|
],
|
|
"request_id": "req_123xyz"
|
|
}
|
|
}
|
|
```
|
|
|
|
## 4. Error Handling
|
|
Frontend clients should check the `success` boolean.
|
|
- If `success` is `false`, read the `error` object.
|
|
- `error.code` maps to standard HTTP status codes but provides application-level context.
|
|
- `error.details` is an optional array of field-specific errors (useful for form validation).
|
|
|
|
## 5. Authentication
|
|
- **Header**: `Authorization: Bearer <token>`
|
|
- **Token Type**: JWT (Access Token)
|
|
- **Refresh**: Use `/api/v1/auth/refresh` to rotate tokens.
|
|
|
|
## 6. Pagination
|
|
Endpoints returning lists support cursor-based or offset-based pagination.
|
|
Helper structure in `data`:
|
|
```json
|
|
{
|
|
"list": [...],
|
|
"pagination": {
|
|
"page": 1,
|
|
"limit": 20,
|
|
"total": 100,
|
|
"has_next": true
|
|
}
|
|
}
|
|
```
|
|
|
|
## 7. Versioning
|
|
- Current Version: `v1`
|
|
- Base Path: `/api/v1`
|
|
|
|
## 8. Key Changes (Remediation Phase)
|
|
- **Unified Handlers**: All handlers now use `RespondSuccess` and `RespondWithAppError`.
|
|
- **Snake Case**: All DTOs enforce `snake_case`.
|
|
- **Validation**: Strict validation on all request bodies using `go-playground/validator`.
|