Vì sao thiết kế API cần nghiêm túc?
API là thứ khó thay đổi nhất sau khi đã phát hành. Một quyết định đặt tên sai có thể theo bạn nhiều năm.
“Hãy thiết kế API như thể bạn sẽ phải hỗ trợ nó mãi mãi.”
Bảy nguyên tắc cốt lõi
- Dùng danh từ số nhiều cho tài nguyên, ví dụ /users.
- Dùng đúng phương thức HTTP.
- Trả về mã trạng thái có ý nghĩa.
- Phân trang cho mọi danh sách.
- Đánh phiên bản ngay từ đầu.
- Thông báo lỗi thống nhất.
- Viết tài liệu song song với mã nguồn.
Mã trạng thái thường dùng
| Mã | Ý nghĩa | Khi nào dùng |
|---|---|---|
| 200 | OK | Thành công |
| 201 | Created | Tạo mới |
| 400 | Bad Request | Dữ liệu sai |
| 404 | Not Found | Không tìm thấy |
Việc cần làm ngay
- Rà soát tên endpoint hiện có.
- Chuẩn hóa định dạng lỗi.
Thiết kế tốt hôm nay, đỡ đau đầu ngày mai.