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


126

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 .



Oprócz powyższego, co powiesz na użycie nagłówka?
zmienna

Odpowiedzi:


40

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.


2
Rozsądnym wnioskiem z powyższej analizy jest to, że idempotentne operacje najlepiej przechowywać w ciągach zapytań adresu URL, a CRUD najlepiej trzymać w ściśle wpisanych ciałach odpowiedzi, co zasadniczo wykorzystuje SOP i zapobiega bardzo podstawowym formom ataków socjotechnicznych / phishingowych
Rice

@Rice R w CRUD jest operacją niezależną.
user398039

16

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.

6

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.


34
Wybór struktury interfejsu API w oparciu o wygodę programowania nie jest dobrą praktyką.
Eric Stein

1
Jak powiedział @EricStein, masz to wstecz.
DanMan,

20
Chłopaki, powodem, dla którego zadałem to pytanie, jest uzyskanie właściwej odpowiedzi. Śmiało, napisz odpowiedź, a ja usunę moją wadliwą. @EricStein
Jonathan

4
@Jonathan apis, które są łatwe do spożycia ludzkimi rękami, są prawie zawsze dobrymi małpami. Brawa za dokładne wywołanie KISS
Chris Marisic

1
@AkshayHiremath Odnosi się do faktu, że możesz wysyłać coś innego w treści, np. Jeśli wysłałeś nagłówek ContentType, taki jak "image / jpeg", musisz mieć treść wiadomości zawierającą dane jpeg i nie możesz umieścić niczego innego w it
Shayaan
Korzystając z naszej strony potwierdzasz, że przeczytałeś(-aś) i rozumiesz nasze zasady używania plików cookie i zasady ochrony prywatności.
Licensed under cc by-sa 3.0 with attribution required.