una - ventajas api rest
¿Cuándo uso los parámetros de ruta frente a los parámetros de consulta en una API RESTful? (7)
Quiero hacer que mi API RESTful sea muy predecible. ¿Cuál es la mejor práctica para decidir cuándo hacer una segmentación de datos usando el URI en lugar de usar parámetros de consulta?
Para mí tiene sentido que los parámetros del sistema que admiten la paginación, la clasificación y la agrupación estén después del ''?'' Pero, ¿qué pasa con los campos como ''estado'' y ''región'' u otros atributos que segmentan su colección? Si también van a ser parámetros de consulta, ¿cuál es la regla general para saber cuándo usar parámetros de ruta?
En términos generales, tiendo a usar parámetros de ruta cuando hay una ''jerarquía'' obvia en el recurso, como:
/region/state/42
Si ese único recurso tiene un estado, uno podría:
/region/state/42/status
Sin embargo, si ''región'' no es realmente parte del recurso expuesto, probablemente pertenece como uno de los parámetros de consulta, similar a la paginación (como mencionó).
En una API REST, no debes preocuparte demasiado por los URI predecibles. La sugerencia misma de la previsibilidad de URI alude a un malentendido de la arquitectura RESTful. Se supone que un cliente debería estar construyendo URI por sí mismo, lo que realmente no debería tener que hacer.
Sin embargo, supongo que no está creando una verdadera API REST, sino una API ''inspirada en REST'' (como la de Google Drive). En estos casos, la regla general es ''parámetros de ruta = identificación de recursos'' y ''parámetros de consulta = clasificación de recursos''. Entonces, la pregunta es, ¿puede identificar de manera única su recurso SIN estado / región? Si es así, entonces quizás sea un parámetro de consulta. Si no, entonces es un camino param.
HTH
La forma fundamental de pensar sobre este tema es la siguiente:
Un URI es un identificador de recurso que identifica de forma exclusiva una instancia específica de un tipo de recurso. Como todo lo demás en la vida, cada objeto (que es una instancia de algún tipo), tiene un conjunto de atributos que son temporales o temporales.
En el ejemplo anterior, un automóvil es un objeto muy tangible que tiene atributos como marca, modelo y VIN, que nunca cambia, y color, suspensión, etc. que pueden cambiar con el tiempo. Entonces, si codificamos el URI con atributos que pueden cambiar con el tiempo (temporal), podemos terminar con múltiples URI para el mismo objeto:
GET /cars/honda/civic/coupe/{vin}/{color=red}
Y años después, si el color de este mismo automóvil cambia a negro:
GET /cars/honda/civic/coupe/{vin}/{color=black}
Tenga en cuenta que la instancia del automóvil en sí (el objeto) no ha cambiado, solo cambió el color. Tener múltiples URI apuntando a la misma instancia de objeto lo obligará a crear múltiples manejadores de URI; este no es un diseño eficiente y, por supuesto, no es intuitivo.
Por lo tanto, el URI solo debe constar de partes que nunca cambiarán y continuarán identificando de manera única ese recurso durante toda su vida útil. Todo lo que pueda cambiar debe reservarse para los parámetros de consulta, como tal:
GET /cars/honda/civic/coupe/{vin}?color={black}
En pocas palabras: piense en el polimorfismo.
La mejor práctica para el diseño de RESTful API es que los parámetros de ruta se usan para identificar un recurso o recursos específicos, mientras que los parámetros de consulta se usan para ordenar / filtrar esos recursos.
Aquí hay un ejemplo. Supongamos que está implementando puntos finales API RESTful para una entidad llamada Car. Estructurarías tus puntos finales de esta manera:
OBTENER
/cars
GET
/cars/:id
POST
/cars
PUT
/cars/:id
DELETE
/cars/:id
De esta manera, solo utiliza parámetros de ruta cuando especifica qué recurso buscar, pero esto no clasifica / filtra los recursos de ninguna manera.
Ahora suponga que desea agregar la capacidad de filtrar los automóviles por color en sus solicitudes GET.
Como el color no es un recurso (es una propiedad de un recurso), puede agregar un parámetro de consulta que lo haga.
Agregaría ese parámetro de consulta a su solicitud
GET
/cars
esta manera:
GET
/cars?color=blue
Este punto final se implementaría para que solo se devolvieran los automóviles azules.
En lo que respecta a la sintaxis, sus nombres de URL deben estar en minúsculas. Si tiene un nombre de entidad que generalmente tiene dos palabras en inglés, usaría un guión para separar las palabras, no el caso de camello.
Ex.
/two-words
La segmentación es más jerárquica y "bonita", pero puede ser limitante.
Por ejemplo, si tiene una url con tres segmentos, cada uno pasa parámetros diferentes para buscar un automóvil por marca, modelo y color:
www.example.com/search/honda/civic/blue
Esta es una url muy bonita y más fácil de recordar para el usuario final, pero ahora te quedas con esta estructura. Digamos que quiere hacerlo para que en la búsqueda el usuario pueda buscar TODOS los automóviles azules o TODOS los Honda Civics. Un parámetro de consulta resuelve esto porque da un par de valores clave. Para que puedas pasar:
www.example.com/search?color=blue
www.example.com/search?make=civic
Ahora tiene una manera de hacer referencia al valor a través de su clave: "color" o "make" en su código de consulta.
Podría solucionar esto posiblemente utilizando más segmentos para crear una especie de estructura de valores clave como:
www.example.com/search/make/honda/model/civic/color/blue
Espero que tenga sentido ..
Una vez diseñé una API cuyo recurso principal eran las
people
.
Por lo general, los usuarios solicitarían
people
filtradas para evitar que los usuarios llamen a algo como
/people?settlement=urban
Además, esto permite acceder a la lista completa
/people
si sería de alguna utilidad más adelante.
En resumen, mi razonamiento fue agregar una ruta a subconjuntos comunes
Desde here :
Alias para consultas comunes
Para que la experiencia API sea más agradable para el consumidor promedio, considere empaquetar conjuntos de condiciones en rutas RESTful de fácil acceso. Por ejemplo, la consulta anterior de tickets recientemente cerrada se podría empaquetar como
GET /tickets/recently_closed
URL de ejemplo:
/rest/{keyword}
Esta URL es un ejemplo de parámetros de ruta.
Podemos obtener estos datos de URL usando
@PathParam
.
Ejemplo de URL:
/rest?keyword=java&limit=10
Esta URL es un ejemplo para los parámetros de consulta.
Podemos obtener estos datos de URL usando
@Queryparam
.