Một API không chỉ là địa chỉ để gửi yêu cầu. Nó còn là thỏa thuận về dữ liệu được chấp nhận, kết quả được trả về và cách giải thích khi không thể hoàn thành. Nếu thỏa thuận này mơ hồ, phía gọi phải thử nhiều lần hoặc dựa vào những chi tiết tình cờ của cách triển khai. Làm rõ hợp đồng từ sớm giúp giảm các phụ thuộc khó nhìn thấy.

Mô tả một tác vụ cụ thể
Hãy lấy ví dụ tạo một ghi chú. Đầu vào có thể gồm tiêu đề và nội dung; đầu ra gồm mã ghi chú cùng dữ liệu đã được lưu. Cần quyết định tiêu đề rỗng có hợp lệ không, độ dài tối đa là bao nhiêu và trường không được biết sẽ bị bỏ qua hay bị từ chối. Những lựa chọn này nên được mô tả để người gọi không phải tự suy luận từ kết quả thử nghiệm.
Không nên nhận cả đối tượng từ phía khách rồi ghi thẳng vào cơ sở dữ liệu. Những trường như người sở hữu hoặc trạng thái duyệt cần được quyết định theo quyền ở phía phục vụ. Danh sách trường đầu vào rõ ràng vừa giúp kiểm tra dữ liệu, vừa tránh việc một trường mới trong cơ sở dữ liệu vô tình trở thành quyền điều khiển của người gọi.
{
"title": "Danh sách việc cần làm",
"body": "Kiểm tra bản sao lưu tuần này"
}
Lỗi cũng là một phần của giao diện
Người gọi cần phân biệt dữ liệu không hợp lệ với việc chưa đăng nhập hoặc dịch vụ tạm thời không sẵn sàng. Một cấu trúc lỗi ổn định có thể gồm mã lỗi cho chương trình và thông điệp dễ hiểu cho người sử dụng. Không trả nguyên lỗi cơ sở dữ liệu hoặc đường dẫn nội bộ chỉ vì chúng thuận tiện lúc phát triển. Thông tin chẩn đoán chi tiết nên được giữ ở nơi có quyền truy cập phù hợp.
| Tình huống | Thông tin cần rõ |
|---|---|
| Thiếu tiêu đề | Trường cần sửa và giới hạn |
| Không có quyền | Tác vụ bị từ chối an toàn |
| Thử lại yêu cầu | Có thể tạo bản ghi trùng hay không |
Kiểm tra từ góc nhìn phía gọi
Một ví dụ thành công chưa đủ để mô tả API. Nên có thêm yêu cầu thiếu trường, dữ liệu vượt giới hạn và truy cập đối tượng không thuộc quyền. Với tác vụ có thể bị gửi lại khi mạng gián đoạn, cần làm rõ cơ chế tránh tạo trùng nếu nghiệp vụ yêu cầu. Không nên mặc định mọi yêu cầu gửi lại đều an toàn chỉ vì phần giao diện đã vô hiệu hóa nút bấm.
Khi hợp đồng thay đổi, hãy xem phía gọi cũ sẽ phản ứng thế nào. Việc thêm trường trả về có thể ít ảnh hưởng hơn đổi ý nghĩa của trường đang có, nhưng vẫn cần kiểm tra theo cách sử dụng thực tế. Tài liệu ngắn đi cùng ví dụ và phép thử giúp hợp đồng trở thành thứ có thể đối chiếu, thay vì một lời hứa nằm ngoài mã nguồn.


Bình luận
Chưa có bình luận.
Đăng nhập để bình luận