API REST Thực tiễn tốt nhất: lập luận trong chuỗi truy vấn so với trong thân yêu cầu

API REST có thể có các đối số ở một số vị trí:

1. Trong phần thân yêu cầu - Là một phần của phần thân json hoặc loại MIME khác
2. Trong chuỗi truy vấn - vd/api/resource?p1=v1&p2=v2
3. Là một phần của đường dẫn URL - ví dụ:/api/resource/v1/v2

Các thực tiễn và cân nhắc tốt nhất về việc lựa chọn giữa 1 và 2 ở trên là gì?
2 vs 3 được bảo hiểm ở đây .

Các thực tiễn và cân nhắc tốt nhất về việc lựa chọn giữa 1 và 2 ở trên là gì?

Thông thường phần thân nội dung được sử dụng cho dữ liệu sẽ được tải lên / tải xuống / từ máy chủ và các tham số truy vấn được sử dụng để chỉ định dữ liệu chính xác được yêu cầu. Ví dụ: khi bạn tải lên một tệp, bạn chỉ định tên, loại mime, v.v. trong phần thân nhưng khi bạn tìm nạp danh sách các tệp, bạn có thể sử dụng các tham số truy vấn để lọc danh sách theo một số thuộc tính của tệp. Nói chung, các tham số truy vấn là thuộc tính của truy vấn không phải dữ liệu.

Tất nhiên đây không phải là một quy tắc nghiêm ngặt - bạn có thể thực hiện nó theo bất kỳ cách nào bạn thấy phù hợp hơn / làm việc cho bạn.

Bạn cũng có thể muốn kiểm tra bài viết trên wikipedia về chuỗi truy vấn , đặc biệt là hai đoạn đầu tiên.

Tôi sẽ cho rằng bạn đang nói về các yêu cầu POST / PUT. Về mặt ngữ nghĩa, cơ quan yêu cầu nên chứa dữ liệu bạn đang đăng hoặc vá.

Chuỗi truy vấn, như một phần của URL (URI), nó ở đó để xác định tài nguyên bạn đang đăng hoặc vá.

Bạn yêu cầu một thực tiễn tốt nhất, sau ngữ nghĩa là của tôi. Tất nhiên sử dụng quy tắc ngón tay cái của bạn sẽ hoạt động, đặc biệt nếu khung web bạn sử dụng trừu tượng này thành các tham số .

Bạn biết nhiều nhất:

• Một số máy chủ web có giới hạn về độ dài của URI.
• Bạn có thể gửi các tham số bên trong thân yêu cầu bằng CURL.
• Nơi bạn gửi dữ liệu không nên có tác dụng trong việc gỡ lỗi.

Sau đây là quy tắc của tôi ...

Khi nào nên sử dụng cơ thể:

• Khi các đối số không có khóa phẳng: cấu trúc giá trị
• Nếu các giá trị không thể đọc được của con người, chẳng hạn như dữ liệu nhị phân được tuần tự hóa
• Khi bạn có một số lượng lớn các đối số

Khi nào nên sử dụng chuỗi truy vấn:

• Khi các đối số là như vậy mà bạn muốn nhìn thấy chúng trong khi gỡ lỗi
• Khi bạn muốn có thể gọi chúng theo cách thủ công trong khi phát triển mã, ví dụ như với curl
• Khi đối số là phổ biến trên nhiều dịch vụ web
• Khi bạn đã gửi một loại nội dung khác, chẳng hạn như application/octet-stream

Lưu ý rằng bạn có thể trộn và kết hợp - đặt những cái phổ biến, những cái nên gỡ lỗi trong chuỗi truy vấn và ném tất cả phần còn lại vào json.