---
name: api-conventions
description: Quy ước thiết kế API nội bộ của công ty — nạp khi viết hoặc sửa endpoint, controller, route, hoặc response format.
user-invocable: false
paths: ["src/api/**", "app/Http/**", "routes/**", "src/routes/**"]
---
Khi viết/sửa API endpoint trong dự án này:
- RESTful naming: danh từ số nhiều, kebab-case; version prefix [ĐIỀN: /api/v1].
- Response envelope thống nhất: [ĐIỀN: ví dụ `{ "data": ..., "error": null, "meta": {...} }`]; lỗi trả `{ "error": { "code", "message" } }` với HTTP status đúng ngữ nghĩa (400 validate, 401/403 auth, 404, 422, 500).
- Validate TẠI BIÊN: [ĐIỀN: FormRequest (Laravel) / zod schema (Node)] — không validate trong service.
- Phân trang chuẩn: query `page`, `per_page` (mặc định [ĐIỀN: 20], max [ĐIỀN: 100]); meta trả `total`, `current_page`.
- Auth: [ĐIỀN: Bearer token/Sanctum]; endpoint mới mặc định CÓ auth middleware trừ khi ghi rõ public.
- Mọi endpoint mới phải kèm: feature test + cập nhật docs/api.md.