Parámetros en la URL (Path Parameters y Query Parameters)

Cuando trabajamos con APIs REST, muchas veces necesitamos especificar o filtrar información en la petición HTTP. Para eso usamos parámetros en la URL, que se dividen en dos tipos principales:

  • Path Parameters: identifican un recurso específico.
  • Query Parameters: filtran o modifican los resultados.

1 Path Parameters

Los Path Parameters (parámetros de ruta) se usan para identificar recursos concretos dentro de la API.

  • Forman parte de la ruta misma.
  • Siempre están dentro de la URL, no después del ?.
  • Generalmente se representan con un ID numérico o un identificador único.

Ejemplo

GET https://api.tienda.com/productos/15

👉 Aquí:

  • /productos es la colección.
  • /15 es el recurso con id = 15.

Respuesta en JSON

{
  "id": 15,
  "nombre": "Notebook",
  "precio": 1500.00
}

Uso en diferentes frameworks

FastAPI (Python)

@app.get("/productos/{id}")
def obtener_producto(id: int):
    return {"id": id, "nombre": "Notebook"}

Express (Node.js)

app.get("/productos/:id", (req, res) => {
  const id = req.params.id;
  res.json({ id, nombre: "Notebook" });
});

👉 En ambos casos, el valor 15 se recibe como variable id.

2 Query Parameters

Los Query Parameters se usan para filtrar, ordenar o modificar los resultados de una petición.

  • Se agregan después del signo de interrogación ?.
  • Se escriben en pares clave=valor.
  • Si hay varios, se separan con &.

Ejemplo

GET https://api.tienda.com/productos?categoria=electronica&orden=precio_desc

👉 Aquí:

  • categoria=electronica filtra productos por categoría.
  • orden=precio_desc ordena los resultados por precio descendente.

Otro ejemplo:

GET https://api.tienda.com/usuarios?activo=true&limite=10

👉 Devuelve los primeros 10 usuarios activos.

Respuesta en JSON (lista filtrada)

[
  { "id": 101, "nombre": "Televisor", "precio": 2500 },
  { "id": 102, "nombre": "Notebook",  "precio": 1500 }
]

3 Diferencias entre Path y Query Parameters

  • Ubicación: Path = parte de la ruta (/productos/15); Query = después del ? (/productos?categoria=ropa).
  • Uso principal: Path = identificar un recurso específico; Query = filtrar, ordenar, limitar resultados.
  • Cantidad: Path = generalmente uno o pocos; Query = puede haber muchos.
  • Ejemplo: /usuarios/5 vs /usuarios?activo=true&limite=10.

👉 Regla práctica: Path define qué recurso quiero. Query define cómo lo quiero.

4 Ejemplos prácticos con APIs

Ejemplo 1 — Usuarios

GET /usuarios/10                         # usuario específico
GET /usuarios?activo=true&limite=5      # usuarios activos con límite

Ejemplo 2 — Pedidos

GET /usuarios/7/pedidos                  # pedidos del usuario 7
GET /pedidos?fecha=2025-09-10            # filtrar por fecha

Ejemplo 3 — Productos

GET /productos/20                        # producto específico
GET /productos?precio_min=1000&precio_max=2000  # rango de precio

5 Ejemplo en Postman

Postman

Path Parameter

URL: https://jsonplaceholder.typicode.com/posts/1
Método: GET

Resultado: un solo post con id = 1.

Query Parameter

URL: https://jsonplaceholder.typicode.com/comments?postId=1
Método: GET

Resultado: comentarios asociados al post con id = 1.

API utilizada: JSONPlaceholder.

6 Ejemplo en cURL

cURL

Path Parameter:

curl https://jsonplaceholder.typicode.com/users/2

Respuesta:

{
  "id": 2,
  "name": "Ervin Howell",
  "email": "Shanna@melissa.tv"
}

Query Parameter:

curl "https://jsonplaceholder.typicode.com/posts?userId=2"

Respuesta: lista de posts del usuario con id = 2.

7 Buenas prácticas en el uso de parámetros

  • Usar Path Parameters para identificar un recurso único. 
    /productos/15     # correcto
/productos?id=15  # evitar
  • Usar Query Parameters para filtros, búsquedas o configuraciones. 
    /productos?orden=precio
/usuarios?activo=true&limite=20
  • Mantener consistencia en nombres: siempre en minúsculas; usar guiones medios si es necesario (fecha-inicio).
  • No abusar de los Query Parameters: si se vuelve muy complejo, pensar en un endpoint específico.

8 Conclusión del capítulo

Los Path Parameters sirven para señalar qué recurso queremos. Los Query Parameters sirven para indicar cómo queremos esos datos (filtrar, ordenar, paginar). El uso correcto de ambos hace que la API sea más clara, flexible y fácil de usar.

👉 En resumen: Path define el recurso, Query define las condiciones.

Retornar