URIs
REST API sử dụng URI
để đánh địa chỉ tài nguyên.
Người thiết kế rest
api nên tạo ra những URI mang tới những thông tin mô tả về tài nguyên của REST
API cho khách hàng.
theo tiêu chuẩn RFC
3986, cú pháp URL :
URI =
scheme://authority/path[?query][#fragment]
Quy tắc #1: Dấu gạch chéo kết thúc không nên được đặt
vào trong URI
Đây là một quy tắc
quan trọng, dấu gạch chéo (/) được thêm vào đằng sau URI không có ý nghĩa và dễ
gây nhầm lẫn. REST API không nên cho dấu này khi cung cấp cho khách hàng
2 URI sau đây là không
tương đương
Nhìn thì giống nhau
nhưng 2 URI khác nhau sẽ dẫn tới 2 tài nguyên khác nhau.
Ta cũng có thể lựa
chọn giải pháp là moved permanently rest api thứ nhất về api thứ 2
Quy tắc #2: Dấu gạch chéo phải được sử dụng để biểu
thị mối quan hệ phân cấp
Dấu gạch chéo được. sử
dụng trong phân chia đường dẫn của URI để biểu thị quan hệ phân cấp trong tài
nguyên
Ví dụ:
Quy tắc #3: Dấu gạch ngang nên được sử dụng để cải
thiện khả năng có thể đọc được của URI
Để tạo cho URI của bạn
dễ dàng cho mọi người có thể đọc và hiểu được, sử dụng dấu gạch ngang (-) trong
những đoạn tên dài. Bất cứ chỗ nào bạn sử dụng giấu cách hoặc dấu gạch ngang
trong ngữ văn thông thường thì bạn nên sử dụng dấu gạch ngang trong URI
Quy tắc #4: Dấu gạch dưới không nên sử dụng trong URI
Những ứng dụng như
trình duyệt, trình soạn thảo văn bản thường gạch chân URI để ra dấu hiệu rằng
chúng có thể click vào được. Phụ thuộc vào font của ứng dụng, dấu gạch chân (_)
có thể bị ẩn đi mất khi font chữ bị gạch dưới
Để tránh khỏi sự nhầm
lẫn này, sử dụng dấu gạch ngang thay vì dấu gạch chân
Quy tắc #5: Kí tự viết thường nên được sử dụng trong
URI
để thuận tiện, kí tự
viết thường thường được ưa dùng hơn kí tự viết hoa bởi 1 số vấn đề. RFC 3986
định nghĩa URI là phân biệt chữ hoa, chững thường ngoại trừ scheme và host
component
Ví dụ:
Đặc
tả định dạng URI RFC 3986 định danh 2 URI này là giống nhau
URI này không giống 2 URI đầu vì thế dễ gây ra nhầm
lẫn ko cần thiết
Quy tắc #6: Phần mở rộng của file
không nên đưa vào trong URI
Trên web, dấu chấm (.) thường được sử dụng để phân
cách tên file và phần mở rộng.
Một REST API thì không nên bao gồm phần này . Thay vào
đó chúng nên dựa vào kiểu dữ liệu trên Content-Type header để xác định khi xử
lý nội dung dữ liệu
phần mở rộng của file
không được được biểu thị ở trên mà ở client nên cung cấp một cơ chế lựa chọn
vào phần Accept header cuả request
Quy tắc #7: Nên đặt tên endpoint là số ít hay số
nhiều?
Một quy tắc đơn giản
được áp dụng là, hãy giữ cho URI có định dạng phù hợp của nó, và nên là số
nhiều
Ví dụ: /students và
/students/12345
Với 1 học sinh có
nhiều khóa học thì logic của endpoint này sẽ là:
/students/12345/courses
Nguồn: https://dzone.com/articles/7-rules-for-rest-api-uri-design-1
No comments:
Post a Comment