Một giao diện lập trình trả về dữ liệu mà không trả về ngữ cảnh của dữ liệu đó sẽ sinh ra hàng loạt phân tích sai — và người viết phân tích không có cách nào biết.
Trả kèm ngữ cảnh
- Nguồn của mỗi trường.
- Ngày cập nhật gần nhất của bản ghi.
- Mức tin cậy nếu giá trị là suy ra.
- Phiên bản dữ liệu.
- Thiếu những thứ này thì người dùng buộc phải giả định, và họ giả định là dữ liệu hoàn hảo.
Phân biệt ba trạng thái
- Có giá trị.
- Đã kiểm và không có giá trị.
- Chưa biết.
- Trả về rỗng cho cả ba là xoá mất thông tin quan trọng nhất.
Ổn định
- Đánh phiên bản, và không đổi nghĩa của trường trong cùng phiên bản.
- Bỏ trường thì báo trước, đừng bỏ đột ngột.
- Thêm trường mới thì được, miễn không phá cấu trúc cũ.
- Đổi nghĩa âm thầm là loại thay đổi gây hại nhất — không có lỗi, chỉ có kết quả sai.
Phân trang và giới hạn
- Kết quả phân trang phải ổn định — không nhảy khi dữ liệu đang cập nhật.
- Trả tổng số nếu biết; nếu không biết thì nói rõ là không biết.
- Nêu giới hạn tốc độ rõ ràng, đừng để người ta dò ra.
- Cắt kết quả im lặng làm người dùng tưởng mình lấy đủ.
Cho tải toàn bộ
- Bản tải đầy đủ định kỳ, định dạng mở.
- Kèm tài liệu mô tả ý nghĩa từng trường.
- Kèm giấy phép rõ ràng.
- Không cho tải toàn bộ thì không ai kiểm độc lập được chất lượng của bạn.
Sai lầm hay gặp
- Trả điểm số tổng hợp mà không giải thích cách tính.
- Cho sắp xếp theo chỉ số, biến giao diện thành công cụ xếp hạng.
- Trộn dữ liệu đã xác nhận với dữ liệu suy ra trong cùng một trường.
- Không nêu giới hạn ở chính chỗ trả dữ liệu.
Một điều đáng nhớ
Phân biệt "không có" với "chưa biết" trong mọi phản hồi.
Gộp hai thứ đó thành một giá trị rỗng là cách âm thầm nhất để biến bao phủ kém thành một tuyên bố về sự thật — và người dùng ở đầu kia không có cách nào phát hiện.
Câu hỏi thường gặp
Giao diện lập trình cần trả kèm gì?
Nguồn của mỗi trường, ngày cập nhật gần nhất, mức tin cậy nếu giá trị là suy ra, và phiên bản dữ liệu — thiếu thì người dùng giả định dữ liệu hoàn hảo.
Ba trạng thái cần phân biệt là gì?
Có giá trị, đã kiểm và không có giá trị, và chưa biết — trả về rỗng cho cả ba là xoá mất thông tin quan trọng nhất.
Làm sao giữ giao diện ổn định?
Đánh phiên bản và không đổi nghĩa của trường trong cùng phiên bản, báo trước khi bỏ trường, và thêm trường mới thì được miễn không phá cấu trúc cũ.
Vì sao phải cho tải toàn bộ dữ liệu?
Vì không cho tải toàn bộ thì không ai kiểm độc lập được chất lượng — bản tải cần định dạng mở, kèm tài liệu mô tả trường và giấy phép rõ ràng.
Sai lầm hay gặp khi thiết kế là gì?
Trả điểm số tổng hợp không giải thích cách tính, cho sắp xếp theo chỉ số biến giao diện thành công cụ xếp hạng, và trộn dữ liệu đã xác nhận với dữ liệu suy ra.
