Best practice per l'API REST: argomenti nella stringa di query rispetto al corpo della richiesta

Un'API REST può avere argomenti in diversi posti:

1. Nel corpo della richiesta : come parte di un corpo json o altro tipo MIME
2. Nella stringa di query - ad es/api/resource?p1=v1&p2=v2
3. Come parte del percorso dell'URL, ad es/api/resource/v1/v2

Quali sono le migliori pratiche e considerazioni per scegliere tra 1 e 2 sopra?
2 vs 3 è coperto qui .

Quali sono le migliori pratiche e considerazioni per scegliere tra 1 e 2 sopra?

Di solito il corpo del contenuto viene utilizzato per i dati che devono essere caricati / scaricati al / dal server e i parametri di query vengono utilizzati per specificare i dati esatti richiesti. Ad esempio, quando carichi un file ne specifichi il nome, il tipo MIME, ecc. Nel corpo, ma quando recuperi l'elenco dei file puoi utilizzare i parametri di query per filtrare l'elenco in base a qualche proprietà dei file. In generale, i parametri della query sono proprietà della query e non dei dati.

Ovviamente questa non è una regola rigida: puoi implementarla in qualsiasi modo ritieni più appropriato / che funzioni per te.

Potresti anche voler controllare l' articolo di wikipedia sulla stringa di query , in particolare i primi due paragrafi.

Presumo che tu stia parlando di richieste POST / PUT. Semanticamente il corpo della richiesta dovrebbe contenere i dati che stai postando o correggendo.

La stringa di query, come parte dell'URL (un URI), serve per identificare la risorsa che stai pubblicando o correggendo.

Hai chiesto una best practice, le seguenti semantiche sono mie. Ovviamente l'uso delle tue regole pratiche dovrebbe funzionare, specialmente se il framework web che usi lo riassume in parametri .

Tu sai di più:

• Alcuni server Web hanno limiti sulla lunghezza dell'URI.
• Puoi inviare parametri all'interno del corpo della richiesta con CURL.
• La posizione in cui invii i dati non dovrebbe avere effetto sul debug.

Le seguenti sono le mie regole pratiche ...

Quando usare il corpo:

• Quando gli argomenti non hanno una chiave semplice: struttura del valore
• Se i valori non sono leggibili dall'uomo, come i dati binari serializzati
• Quando hai un numero molto elevato di argomenti

Quando utilizzare la stringa di query:

• Quando gli argomenti sono tali da volerli vedere durante il debug
• Quando vuoi essere in grado di chiamarli manualmente durante lo sviluppo del codice, ad esempio con curl
• Quando gli argomenti sono comuni a molti servizi web
• Quando stai già inviando un tipo di contenuto diverso come application/octet-stream

Nota che puoi mescolare e abbinare: metti quelli comuni, quelli che dovrebbero essere debugabili nella stringa di query e getta tutto il resto nel json.