RESTful API là lớp kết nối giữa hệ thống quản trị, ứng dụng mobile, dashboard, cổng dữ liệu và các phần mềm bên thứ ba. Vì vậy, thiết kế API cần đặt trọng tâm vào tính nhất quán, bảo mật và khả năng vận hành lâu dài.
Thiết kế endpoint theo tài nguyên
Endpoint nên phản ánh tài nguyên nghiệp vụ thay vì hành động rời rạc. Ví dụ, hồ sơ môi trường, dự án, giấy phép, điểm quan trắc hay báo cáo đều có thể được mô hình hóa thành tài nguyên có danh sách, chi tiết và lịch sử cập nhật.
Khi API dùng danh từ rõ ràng, đội frontend, mobile và đối tác tích hợp dễ đoán cấu trúc hơn. Điều này giảm thời gian trao đổi và hạn chế lỗi hiểu sai nghiệp vụ.
- Dùng GET để lấy dữ liệu, POST để tạo mới, PUT/PATCH để cập nhật và DELETE để xóa.
- Giữ quy ước đặt tên số nhiều cho các tập tài nguyên.
- Tách API public, API nội bộ và API quản trị nếu quyền truy cập khác nhau.
Phân trang, lọc và sắp xếp
Danh sách dữ liệu thường lớn dần theo thời gian. Nếu API trả toàn bộ dữ liệu trong một request, hệ thống sẽ chậm và khó kiểm soát tài nguyên server. Phân trang, lọc theo trạng thái và sắp xếp theo thời gian là những yêu cầu cơ bản.
Với dữ liệu chuyên ngành, nên thống nhất mã danh mục từ đầu. Các trường như địa bàn, loại hồ sơ, trạng thái xử lý hoặc kỳ báo cáo nên có giá trị chuẩn để backend và frontend lọc dữ liệu đồng nhất.
Bảo mật và tài liệu hóa
API cần xác thực, phân quyền và giới hạn tốc độ truy cập. Những API chứa dữ liệu nhạy cảm như hồ sơ doanh nghiệp, tọa độ tài nguyên hoặc kết quả quan trắc cần log truy cập để phục vụ kiểm tra sau này.
Tài liệu OpenAPI hoặc tài liệu nội bộ giúp đội phát triển hiểu request, response, mã lỗi và ví dụ dữ liệu. Tài liệu nên được cập nhật cùng code, nếu không rất nhanh lỗi thời.
- Trả mã lỗi thống nhất và có thông điệp dễ hiểu.
- Không để lộ thông tin hệ thống trong response lỗi.
- Ghi log các request quan trọng để phục vụ truy vết.
- Versioning API khi thay đổi contract lớn.
Tóm tắt ý chính
- API tốt cần ổn định contract, rõ mã lỗi và có tài liệu.
- Phân trang, lọc, sắp xếp là bắt buộc với dữ liệu lớn.
- Bảo mật API phải đi cùng xác thực, phân quyền và log truy cập.
