Bắt đầu từ hợp đồng dữ liệu

Trước khi viết endpoint, hãy xác định ai sử dụng dữ liệu và họ cần hoàn thành việc gì. Một danh sách chỉ cần tiêu đề, trạng thái và ảnh thu nhỏ thường không nên trả về toàn bộ nội dung dài của mỗi bản ghi. Phạm vi phản hồi nhỏ giúp cả máy chủ lẫn giao diện làm việc nhẹ hơn.

Quy định rõ kiểu dữ liệu, giới hạn độ dài, trường có thể bỏ trống và cách phân trang. Những chi tiết này nên được kiểm tra tại máy chủ, kể cả khi giao diện đã có kiểm tra riêng. Dữ liệu từ trình duyệt không phải một nguồn đáng tin cậy.

Lỗi cũng là một phần giao diện

Một thông báo lỗi tốt giúp bên gọi API biết cần sửa gì. Phân biệt dữ liệu không hợp lệ, thiếu quyền và dữ liệu đã thay đổi. Không đưa đường dẫn nội bộ, câu truy vấn hay thông tin nhạy cảm vào phản hồi công khai.

Khi nhiều người có thể sửa cùng một bản ghi, dùng phiên bản bản ghi để phát hiện cập nhật chồng lên nhau. Thay vì âm thầm ghi đè, hệ thống có thể yêu cầu tải lại nội dung mới nhất.

Thiết kế cho lần thay đổi tiếp theo

Giữ cách đặt tên và cấu trúc phản hồi nhất quán. Ghi lại những tình huống biên quan trọng bằng kiểm thử: bản ghi đã bị xoá, người dùng mất quyền, thao tác gửi lặp và dữ liệu quá giới hạn. Một API dễ bảo trì là API có hành vi dễ dự đoán, ngay cả khi yêu cầu không diễn ra như mong đợi.