Thiết kế API web dễ dùng và bền vững theo thời gian
API là cầu nối giữa các phần của một hệ thống và giữa sản phẩm của bạn với thế giới bên ngoài. Một API được thiết kế tốt giúp các đội khác tích hợp nhanh chóng và ít mắc lỗi, trong khi một API thiết kế kém sẽ trở thành nguồn gốc của vô số phiền toái kéo dài nhiều năm. Khác với code nội bộ có thể sửa tự do, API một khi đã công bố và có người sử dụng thì rất khó thay đổi, nên việc thiết kế cẩn thận ngay từ đầu mang ý nghĩa đặc biệt quan trọng.
Nhất quán là phẩm chất quan trọng nhất
Khi làm việc với một API, lập trình viên xây dựng dần một mô hình tinh thần về cách nó hoạt động. Nếu API nhất quán, họ có thể đoán đúng cách dùng những phần chưa từng chạm tới, dựa trên những gì đã học được. Sự nhất quán thể hiện ở nhiều khía cạnh: quy ước đặt tên tài nguyên, cách phân trang, định dạng ngày giờ, cấu trúc thông báo lỗi. Nếu một điểm cuối dùng số nhiều cho tài nguyên thì tất cả nên làm vậy; nếu một nơi trả về thời gian theo chuẩn quốc tế thì mọi nơi nên thống nhất.
Với API theo phong cách REST, hãy mô hình hóa hệ thống quanh các tài nguyên danh từ và sử dụng phương thức HTTP đúng ngữ nghĩa của chúng. Phương thức đọc dữ liệu không được thay đổi trạng thái, phương thức tạo mới khác với phương thức cập nhật, và phương thức xóa cần có tính bình ổn để gọi lại nhiều lần không gây hậu quả ngoài ý muốn. Sự tôn trọng ngữ nghĩa này giúp API hành xử đúng với hạ tầng web như bộ nhớ đệm và proxy.
Mã trạng thái và thông báo lỗi rõ ràng
Cách một API phản hồi khi mọi thứ suôn sẻ thì dễ, nhưng chất lượng thật sự lộ ra ở cách nó xử lý lỗi. Hãy dùng đúng mã trạng thái HTTP để bên gọi biết chuyện gì đã xảy ra mà không phải đoán: phân biệt rõ giữa lỗi do phía người dùng gửi dữ liệu sai và lỗi do phía máy chủ. Quan trọng hơn, thân phản hồi lỗi nên chứa thông tin hữu ích.
- Một mã lỗi ổn định để bên gọi xử lý theo chương trình mà không phải phân tích chuỗi văn bản.
- Một thông điệp dễ đọc dành cho lập trình viên đang gỡ lỗi.
- Chi tiết về trường nào bị sai khi dữ liệu đầu vào không hợp lệ, giúp người dùng sửa nhanh.
Thông báo lỗi mơ hồ kiểu đã xảy ra lỗi buộc người tích hợp phải mò mẫm, gửi yêu cầu hỗ trợ và lãng phí thời gian của cả hai bên. Đầu tư vào thông báo lỗi rõ ràng là một trong những cách rẻ nhất để cải thiện trải nghiệm của người dùng API.
Lập phiên bản và khả năng tiến hóa
API sẽ phải thay đổi khi nhu cầu nghiệp vụ thay đổi, nhưng bạn không thể buộc tất cả người dùng cập nhật cùng lúc. Vì vậy, hãy lên kế hoạch cho sự tiến hóa ngay từ đầu. Một chiến lược an toàn là thiết kế để có thể thêm trường mới mà không phá vỡ bên gọi cũ; bên gọi nên bỏ qua những trường chúng không nhận ra thay vì báo lỗi. Những thay đổi phá vỡ tương thích, như đổi tên trường hay thay đổi kiểu dữ liệu, cần được đưa vào một phiên bản mới và có lộ trình ngừng hỗ trợ phiên bản cũ rõ ràng.
Hãy truyền đạt những thay đổi này một cách minh bạch. Người dùng API cần biết trước khi một tính năng bị loại bỏ, cần thời gian để di chuyển, và cần tài liệu mô tả con đường nâng cấp. Sự tôn trọng này xây dựng lòng tin và giữ chân người dùng.
Tài liệu là một phần của sản phẩm
Một API dù thiết kế tốt đến đâu cũng vô dụng nếu không ai biết cách dùng. Tài liệu không phải phần phụ thêm sau cùng mà là một phần cốt lõi của trải nghiệm. Tài liệu tốt cần có mô tả từng điểm cuối, các tham số, định dạng phản hồi, và đặc biệt là ví dụ thực tế mà người đọc có thể sao chép và chạy thử ngay. Một ví dụ chạy được đáng giá hơn nhiều đoạn mô tả trừu tượng.
Ngoài ra, hãy nghĩ đến trải nghiệm của người mới bắt đầu. Một hướng dẫn nhanh giúp họ thực hiện thành công lệnh gọi đầu tiên trong vài phút sẽ tạo ấn tượng mạnh mẽ và quyết định liệu họ có tiếp tục dùng sản phẩm của bạn hay không. Thiết kế API rốt cuộc là một bài tập về sự đồng cảm: bạn đang viết cho những lập trình viên khác, những người sẽ đánh giá công sức của bạn qua mức độ dễ chịu khi làm việc cùng giao diện bạn tạo ra.
