Mejores prácticas de la API REST: argumentos en la cadena de consulta frente al cuerpo de la solicitud

Una API REST puede tener argumentos en varios lugares:

1. En el cuerpo de la solicitud : como parte de un cuerpo json u otro tipo MIME
2. En la cadena de consulta , p. Ej./api/resource?p1=v1&p2=v2
3. Como parte de la ruta URL , p. Ej./api/resource/v1/v2

¿Cuáles son las mejores prácticas y consideraciones para elegir entre 1 y 2 anteriores?
2 vs 3 está cubierto aquí .

¿Cuáles son las mejores prácticas y consideraciones para elegir entre 1 y 2 anteriores?

Por lo general, el cuerpo del contenido se usa para los datos que se van a cargar / descargar al / desde el servidor y los parámetros de consulta se usan para especificar los datos exactos solicitados. Por ejemplo, cuando carga un archivo, especifica el nombre, el tipo de mímica, etc. en el cuerpo, pero cuando busca una lista de archivos, puede usar los parámetros de consulta para filtrar la lista por alguna propiedad de los archivos. En general, los parámetros de la consulta son propiedad de la consulta, no de los datos.

Por supuesto, esta no es una regla estricta, puede implementarla de la manera que considere más apropiada / que funcione para usted.

También puede consultar el artículo de wikipedia sobre la cadena de consulta , especialmente los dos primeros párrafos.

Asumiré que está hablando de solicitudes POST / PUT. Semánticamente, el cuerpo de la solicitud debe contener los datos que está publicando o parcheando.

La cadena de consulta, como parte de la URL (un URI), está ahí para identificar qué recurso está publicando o parcheando.

Usted pidió las mejores prácticas, la siguiente semántica es mía. Por supuesto, usar sus reglas generales debería funcionar, especialmente si el marco web que usa abstrae esto en parámetros .

Que más sabes:

• Algunos servidores web tienen límites en la longitud del URI.
• Puede enviar parámetros dentro del cuerpo de la solicitud con CURL.
• El lugar al que envíe los datos no debería afectar a la depuración.

Las siguientes son mis reglas generales ...

Cuándo usar el cuerpo:

• Cuando los argumentos no tienen una clave plana: estructura de valor
• Si los valores no son legibles por humanos, como datos binarios serializados
• Cuando tienes una gran cantidad de argumentos

Cuándo usar la cadena de consulta:

• Cuando los argumentos son tales que desea verlos mientras depura
• Cuando desee poder llamarlos manualmente mientras desarrolla el código, por ejemplo, con curl
• Cuando los argumentos son comunes en muchos servicios web
• Cuando ya está enviando un tipo de contenido diferente, como application/octet-stream

Tenga en cuenta que puede mezclar y combinar: coloque los comunes, los que deberían ser depurables en la cadena de consulta, y arroje todo el resto en el json.