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


125

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í .



Además de lo anterior, ¿qué tal usar el encabezado?
variable

Respuestas:


39

¿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.


1
Una conclusión razonable de su análisis anterior es que las operaciones idempotentes se mantienen mejor en las cadenas de consulta de URL y CRUD se mantiene mejor en cuerpos de respuesta estrictamente tipados, que esencialmente aprovechan SOP y previenen formas muy básicas de ingeniería social / ataques de phishing
Rice

15

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.

6

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.


34
Seleccionar cómo estructurar su API según la conveniencia del desarrollo no es una buena práctica.
Eric Stein

1
Como dijo @EricStein, lo tienes al revés.
DanMan

20
Chicos, la razón por la que hice la pregunta es para obtener la respuesta correcta. Adelante, escribe una respuesta y eliminaré la defectuosa. @EricStein
Jonathan

4
Las apis de @Jonathan que son fáciles de consumir a través de manos humanas son casi siempre buenas apis. Felicitaciones por llamar con precisión a KISS
Chris Marisic

1
@AkshayHiremath Se refiere al hecho de que podría estar enviando algo más en el cuerpo, por ejemplo, si envió un encabezado ContentType como "image / jpeg", necesitaría que el cuerpo del mensaje contenga los datos jpeg y no podría incluir nada más en it
Shayaan
Al usar nuestro sitio, usted reconoce que ha leído y comprende nuestra Política de Cookies y Política de Privacidad.
Licensed under cc by-sa 3.0 with attribution required.