Khi định nghĩa API specs cho RESTful API, có một số naming convention là best practice mà các bạn nên follow để các API specs này có thể nhất quán, trực quan và dễ bảo trì.
Đó là các nguyên tắc như sau:
- Sử dụng danh từ (noun), thay vì động từ (verb) khi naming cho các resources
Thay vì /getStudents, các bạn nên naming là /students
- Sử dụng danh từ số nhiều (plural) cho collection của các resources, số ít (singular) cho một resource
Thay vì /student, các bạn nên naming là /students cho collection, /students/{id} cho một resource.
- Sử dụng HTTP method để định nghĩa các action
-
- GET /students → Lấy danh sách sinh viên
- GET /students/{id} → Lấy thông tin của một sinh viên
- POST /students → Thêm mới sinh viên
- PUT /students/{id} → Cập nhập thông tin sinh viên
- PATCH /students/{id} → Cập nhập một phần thông tin sinh viên
- DELETE /students/{id} → Xoá thông tin của một sinh viên
- Sử dụng chữ viết thường (lowercase) với dấu gạch ngang (hyphen), không sử dụng camelCase hay snake_case
Thay vì /studentProfiles hay /student_profiles, chúng ta nên naming là /student-profiles
- Nếu các resources của các bạn có mối quan hệ với nhau thì hãy naming theo phân cấp với dấu gạch chéo
Thay vì /getStudentSubjects để lấy thông tin các môn học của sinh viên, các bạn có thể naming /students/{id}/subjects hoặc /students/{id}/subjects/{id}
- Sử dụng query parameters để lọc (filtering), sắp xếp (sorting), phân trang (pagination), tìm kiếm (searching)
Ví dụ như /students?classId=1A&sort=createdAt&limit=10&page=2
Trên đây là những nguyên tắc cơ bản, các bạn hãy cố gắng follow theo nhé!
