Best Practices für die REST-API: Argumente in der Abfragezeichenfolge im Vergleich zum Anforderungshauptteil

Eine REST-API kann an mehreren Stellen Argumente enthalten:

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. Im Rahmen des URL-Pfades - z/api/resource/v1/v2

Was sind die Best Practices und Überlegungen zur Auswahl zwischen 1 und 2 oben?
2 gegen 3 wird hier behandelt .

Was sind die Best Practices und Überlegungen zur Auswahl zwischen 1 und 2 oben?

Normalerweise wird der Inhaltskörper für die Daten verwendet, die zum / vom Server hochgeladen / 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 Hauptteil an. Wenn Sie jedoch eine Liste von Dateien abrufen, können Sie die Abfrageparameter verwenden, um die Liste nach einer Eigenschaft der Dateien zu filtern. Im Allgemeinen sind die Abfrageparameter Eigentum der Abfrage und nicht der Daten.

Natürlich ist dies 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 den Wikipedia-Artikel über Abfragezeichenfolgen lesen , insbesondere die ersten beiden Absätze.

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

Die Abfragezeichenfolge dient als Teil der URL (einer URI) dazu, zu identifizieren, welche Ressource Sie veröffentlichen oder patchen.

Sie haben nach Best Practices gefragt. Die folgende Semantik gehört mir. Natürlich sollte die Verwendung Ihrer Faustregeln funktionieren, insbesondere wenn das von Ihnen verwendete Webframework dies in Parameter abstrahiert .

Sie wissen am meisten:

• Einige Webserver haben Grenzen für die Länge des URI.
• Sie können mit CURL Parameter innerhalb des Anforderungshauptteils senden.
• Wohin Sie die Daten senden, sollte sich nicht auf das Debuggen auswirken.

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 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 während der Entwicklung des Codes manuell aufrufen möchten, z. B. mit curl
• Wenn Argumente für viele Webdienste gleich sind
• Wenn Sie bereits einen anderen Inhaltstyp senden, z application/octet-stream

Beachten Sie, dass Sie mischen und abgleichen können - fügen Sie die allgemeinen, diejenigen, die debuggbar sein sollten, in die Abfragezeichenfolge ein und werfen Sie den Rest in den json.