it-swarm.com.de

REST API Best Practices: Argumente in Abfragezeichenfolge vs im Anforderungshauptteil

Eine REST API kann an mehreren Stellen Argumente haben:

  1. Im Anforderungshauptteil - Als Teil eines JSON-Hauptteils oder eines anderen MIME-Typs
  2. In der Abfragezeichenfolge - z. /api/resource?p1=v1&p2=v2
  3. Als Teil des URL-Pfads - z. /api/resource/v1/v2

Was sind die bewährten Methoden und Überlegungen für die Auswahl zwischen 1 und 2 oben?
2 vs 3 wird behandelt hier .

74
Jonathan

Was sind die Best Practices und Überlegungen für die Auswahl zwischen 1 und 2 oben?

Normalerweise wird der Inhaltshauptteil für die Daten verwendet, die auf den Server hochgeladen/von ihm heruntergeladen werden sollen, und die Abfrageparameter werden verwendet, um die genauen angeforderten Daten anzugeben. Wenn Sie beispielsweise eine Datei hochladen, geben Sie den Namen, den MIME-Typ usw. im Body an. Wenn Sie jedoch eine Liste von Dateien abrufen, können Sie die Liste mit den Abfrageparametern nach bestimmten Eigenschaften der Dateien filtern. Im Allgemeinen sind die Abfrageparameter Eigentum der Abfrage, nicht der Daten.

Dies ist natürlich keine strenge Regel - Sie können sie so implementieren, wie Sie es für angemessener halten/für Sie arbeiten.

Vielleicht möchten Sie auch das Wikipedia-Artikel über Abfragezeichenfolge überprüfen, insbesondere die ersten beiden Absätze.

23
stan0

Ich gehe davon aus, dass Sie über POST/PUT-Anforderungen sprechen. Semantisch sollte der Anfragetext die Daten enthalten, die Sie veröffentlichen oder patchen.

Die Abfragezeichenfolge als Teil der URL (ein URI) gibt an, welche Ressource Sie bereitstellen oder patchen.

Sie haben nach Best Practices gefragt, die folgenden Semantiken gehören mir. Natürlich sollte die Verwendung Ihrer Faustregeln funktionieren, insbesondere wenn das von Ihnen verwendete Web-Framework dies in Parameter abstrahiert.

Sie wissen am meisten:

  • Bei einigen Webservern ist die Länge der URI begrenzt.
  • Sie können mit CURL Parameter innerhalb des Anforderungskörpers senden.
  • Wohin Sie die Daten senden, sollte sich nicht auf das Debuggen auswirken.
11
Leonel Galán

Das Folgende sind meine Faustregeln ...

Wann man den Körper benutzt:

  • Wenn die Argumente keinen flachen Schlüssel haben: Wertestruktur
  • Wenn die Werte nicht für den Menschen lesbar sind, z. B. serialisierte Binärdaten
  • Wenn Sie eine sehr große Anzahl von Argumenten haben

Wann wird die Abfragezeichenfolge verwendet?

  • Wenn die Argumente so sind, dass Sie sie beim Debuggen sehen möchten
  • Wenn Sie sie manuell aufrufen möchten, während Sie den Code entwickeln, z. mit curl
  • Wenn Argumente in vielen Webdiensten gleich sind
  • Wenn Sie bereits einen anderen Inhaltstyp senden, z. B. application/octet-stream

Beachten Sie, dass Sie mischen und abgleichen können - fügen Sie die allgemeinen, die debugfähig sein sollen, in die Abfragezeichenfolge ein und werfen Sie den Rest in den JSON-Code.

5
Jonathan