Thiết kế API REST: versioning và error format

Versioning

API thay đổi theo thời gian; versioning giúp client cũ vẫn chạy trong khi client mới dùng tính năng mới. Cách phổ biến: prefix URL /v1/, /v2/ hoặc header Accept-Version. Một số dùng query ?version=1. Chọn một và thống nhất.

Error format thống nhất

Trả về HTTP status đúng (4xx client, 5xx server). Body JSON nhất quán: code, message, details (validation errors). Tránh lộ stack trace ở production. Log đầy đủ phía server để debug.

Pagination và filter

List API nên có limit/offset hoặc cursor. Trả về meta (total, hasMore, nextCursor). Filter theo query param (?status=active&sort=-created_at). Document rõ trong OpenAPI/Swagger.