virtus
c985df7579
Build and Push Reader API Image / docker (push) Successful in 1m3s
- Updated `.env.example` to remove MongoDB configuration. - Revised `ARCHITECTURE.md` to reflect changes in data orchestration and storage strategy. - Removed `CHAPTER_SAVE_DEBUG.md` and `FIXES_APPLIED.md` as they are no longer relevant. - Updated `CONTRACT.md` to include new error codes. - Adjusted endpoint documentation in `CROSS_REPO_ENDPOINT_MATRIX.md` and `README.md` to align with the new import flow. - Removed legacy import scripts and tables from the codebase.
66 lines
1.4 KiB
Markdown
66 lines
1.4 KiB
Markdown
# API Contract Standard (Reader Suite)
|
|
|
|
Tai lieu contract chung cho `reader`, `reader-app`, `reader-api`.
|
|
|
|
## Base and Versioning
|
|
|
|
- Base path: `/api/*`
|
|
- Current mode: unversioned with backward-compatible evolution.
|
|
- Breaking changes bat buoc qua ke hoach migration va release note.
|
|
|
|
## Response Convention
|
|
|
|
- Success:
|
|
- `200/201`: tra JSON payload domain data.
|
|
- `204`: khong co body.
|
|
- Error (standardized):
|
|
|
|
```json
|
|
{
|
|
"code": "string",
|
|
"message": "human readable",
|
|
"details": {}
|
|
}
|
|
```
|
|
|
|
## HTTP Status Usage
|
|
|
|
- `400`: input/validation khong hop le.
|
|
- `401`: chua dang nhap hoặc token/session invalid.
|
|
- `403`: da dang nhap nhung khong du quyen.
|
|
- `404`: resource khong ton tai.
|
|
- `409`: xung dot du lieu.
|
|
- `422`: payload format dung JSON nhung khong dat rule nghiep vu.
|
|
- `500`: loi he thong.
|
|
- `410`: (du tru) tai nguyen da go bo hoac khong con ho tro.
|
|
|
|
## Pagination Convention
|
|
|
|
- Query params: `page`, `limit`.
|
|
- Response envelope:
|
|
|
|
```json
|
|
{
|
|
"items": [],
|
|
"pagination": {
|
|
"page": 1,
|
|
"limit": 20,
|
|
"total": 0,
|
|
"totalPages": 0
|
|
}
|
|
}
|
|
```
|
|
|
|
## Auth Matrix
|
|
|
|
- Web: NextAuth session cookie.
|
|
- Mobile: Bearer JWT.
|
|
- Backend phai map ca 2 vao cung user identity + role.
|
|
|
|
## Compatibility Rules
|
|
|
|
- Khong xoa hoac doi y nghia field dang duoc client su dung.
|
|
- Field moi phai optional theo default trong giai doan rollout.
|
|
- Doi ten field => tao migration layer hoac add field moi, deprecate sau.
|
|
- Endpoint moi can update README + mapping matrix.
|