¿Cuando usar Paths o Querys en un API REST?

Tiempo de lectura: 2 minutos

En el desarrollo de APIs REST, tanto las queries como los paths tienen sus usos específicos y sus ventajas. A continuación, te doy una guía sobre cuándo deberías usar cada uno:

Usar Paths

Los paths se usan para identificar recursos específicos o colecciones de recursos. Se utilizan en la URL para definir una jerarquía clara y estructurada de los recursos. Algunas reglas comunes para el uso de paths incluyen:

1. Recursos específicos:

• Cuando necesitas acceder, actualizar o eliminar un recurso específico.
• Ejemplo: /usuarios/123 accede al usuario con el ID 123.

1. Colecciones de recursos:

• Para acceder a una colección de recursos.
• Ejemplo: /usuarios accede a la colección de todos los usuarios.

1. Relaciones jerárquicas:

• Para reflejar relaciones jerárquicas entre recursos.
• Ejemplo: /usuarios/123/ordenes accede a todas las órdenes del usuario con el ID 123.

1. Operaciones de sub-recursos:

• Cuando se necesita realizar operaciones en sub-recursos.
• Ejemplo: /usuarios/123/ordenes/456 accede a la orden 456 del usuario 123.

Usar Queries

Las queries se utilizan para modificar la representación de un recurso o para realizar búsquedas y filtrados en colecciones. Se pasan como parámetros de la URL y permiten especificar condiciones o modificar el comportamiento de la solicitud. Algunas reglas comunes para el uso de queries incluyen:

1. Filtrado de colecciones:

• Para filtrar resultados basados en ciertos criterios.
• Ejemplo: /usuarios?edad=30 obtiene todos los usuarios con edad 30.

1. Paginación:

• Para dividir los resultados en páginas.
• Ejemplo: /usuarios?page=2&limit=10 obtiene la segunda página de resultados con 10 usuarios por página.

1. Ordenación:

• Para especificar el orden en que se deben devolver los resultados.
• Ejemplo: /usuarios?sort=nombre ordena los usuarios por nombre.

1. Búsqueda:

• Para realizar búsquedas complejas en una colección.
• Ejemplo: /productos?nombre=televisor&marca=Samsung busca productos con nombre «televisor» y marca «Samsung».

1. Opciones de proyección:

• Para seleccionar qué campos deben ser devueltos.
• Ejemplo: /usuarios?fields=nombre,apellido devuelve solo los campos nombre y apellido de los usuarios.

Ejemplos Prácticos

• Acceder a un recurso específico:

  GET /usuarios/123

• Filtrar recursos en una colección:

  GET /usuarios?ciudad=Madrid

• Realizar una operación en un sub-recurso:

  DELETE /usuarios/123/ordenes/456

• Paginar y ordenar una colección:

  GET /productos?categoria=electrodomesticos&sort=precio&order=desc&page=2&limit=10

Paths: Se usan para identificar recursos y su jerarquía.

• Queries: Se usan para modificar la representación de los recursos o para realizar búsquedas y filtrados.

Usar estos elementos correctamente hace que tu API REST sea más intuitiva, fácil de usar y de mantener.