Najlepsze rozwiązania dotyczące interfejsu API REST: argumenty w ciągu zapytania a treść żądania

REST API może mieć argumenty w kilku miejscach:

1. W treści żądania - jako część treści json lub innego typu MIME
2. W ciągu zapytania - np/api/resource?p1=v1&p2=v2
3. W ramach ścieżki URL - np/api/resource/v1/v2

Jakie są najlepsze praktyki i kwestie do rozważenia przy wyborze między 1 a 2 powyżej?
2 na 3 jest tutaj omówione .

Jakie są najlepsze praktyki i kwestie do rozważenia przy wyborze między 1 a 2 powyżej?

Zwykle treść treści jest używana dla danych, które mają być przesłane / pobrane na / z serwera, a parametry zapytania są używane do określenia dokładnych żądanych danych. Na przykład, kiedy przesyłasz plik, określasz nazwę, typ MIME itp. W treści, ale podczas pobierania listy plików możesz użyć parametrów zapytania, aby przefiltrować listę według jakiejś właściwości plików. Ogólnie parametry zapytania są właściwością zapytania, a nie danymi.

Oczywiście nie jest to ścisła zasada - możesz ją wdrożyć w dowolny sposób, który Ci odpowiada.

Możesz również zapoznać się z artykułem w Wikipedii o ciągu zapytania , zwłaszcza z dwoma pierwszymi akapitami.

Zakładam, że mówisz o żądaniach POST / PUT. Pod względem semantycznym treść żądania powinna zawierać dane, które publikujesz lub poprawiasz.

Ciąg zapytania, jako część adresu URL (URI), służy do identyfikacji zasobu, który publikujesz lub aktualizujesz.

Poprosiłeś o najlepsze praktyki, przestrzeganie semantyki jest moje. Oczywiście używanie praktycznych reguł powinno działać, szczególnie jeśli framework sieciowy, którego używasz, jest abstrakcyjny w parametrach .

Wiesz najbardziej:

• Niektóre serwery internetowe mają ograniczenia długości identyfikatora URI.
• Możesz wysyłać parametry wewnątrz treści żądania za pomocą CURL.
• Miejsce, w którym wysyłasz dane, nie powinno mieć wpływu na debugowanie.

Oto moje praktyczne zasady ...

Kiedy używać ciała:

• Gdy argumenty nie mają płaskiej struktury klucz: wartość
• Jeśli wartości nie są czytelne dla człowieka, na przykład zserializowane dane binarne
• Gdy masz bardzo dużą liczbę argumentów

Kiedy używać ciągu zapytania:

• Gdy argumenty są takie, że chcesz je zobaczyć podczas debugowania
• Gdy chcesz mieć możliwość ich ręcznego wywoływania podczas tworzenia kodu np. Za pomocą curl
• Gdy argumenty są wspólne dla wielu usług internetowych
• Kiedy już wysyłasz inny typ zawartości, na przykład application/octet-stream

Zauważ, że możesz mieszać i dopasowywać - umieść te typowe, te, które powinny być debugowalne w ciągu zapytania, a całą resztę wrzuć do json.