Endpoints y rutas en una API REST

En una API REST, los endpoints son las direcciones a las que los clientes acceden mediante el protocolo HTTP. Cada endpoint es una URL única que apunta a un recurso.

1 ¿Qué es un endpoint?

Un endpoint es la URL única donde un cliente (app, navegador, programa) puede acceder a un recurso específico de la API REST.

👉 Podés imaginarlo como la dirección exacta de una casa:

  • La API es como una ciudad.
  • Los recursos (usuarios, productos, pedidos) son casas.
  • Los endpoints son las direcciones que permiten llegar a cada casa.

Ejemplo

https://api.tienda.com/productos/15
  • https://api.tienda.com: dominio de la API.
  • /productos: colección de recursos (productos).
  • /15: recurso específico (producto con ID = 15).

2 Rutas en una API REST

Una ruta es la parte de la URL que indica qué recurso queremos. Las rutas deben ser:

  • Predecibles: que se entienda qué devuelve.
  • Jerárquicas: siguiendo una estructura lógica.
  • Consistentes: todas con el mismo formato.

Ejemplos

GET /usuarios            # lista de usuarios
GET /usuarios/1          # usuario con id=1
POST /usuarios           # crear un usuario
PUT /usuarios/1          # actualizar usuario con id=1
DELETE /usuarios/1       # eliminar usuario con id=1

3 Uso de nombres en plural

En REST, los recursos se nombran en plural.

  • Correcto: /usuarios, /productos, /pedidos.
  • Incorrecto: /usuario, /producto, /pedido.

👉 La razón es que las rutas representan colecciones de objetos.

4 Jerarquía y subrutas

Muchas veces un recurso está relacionado con otro. Para representar estas relaciones, se usan subrutas.

Ejemplos

/usuarios/1/pedidos       # pedidos que pertenecen al usuario con id=1
/productos/15/comentarios # comentarios asociados al producto con id=15

Esto mantiene la API organizada y fácil de entender.

5 Parámetros en rutas (Path Parameters)

Un Path Parameter es una parte de la ruta que representa un valor variable y se usa para identificar un recurso específico.

Ejemplo

/usuarios/1

👉 El número 1 es el id del usuario.

En frameworks como FastAPI o Express se define con llaves o con dos puntos:

/usuarios/{id}
/usuarios/:id

6 Query Parameters

A veces necesitamos filtrar o personalizar los datos de una petición. Para eso se usan los Query Parameters, que se agregan después de un signo ? en la URL.

Ejemplo

/productos?categoria=electronica&orden=precio_desc

👉 Esta ruta devolvería los productos de la categoría electrónica, ordenados por precio descendente.

Otro ejemplo:

/usuarios?activo=true&limite=10

👉 Devuelve los primeros 10 usuarios activos.

7 Ejemplos de endpoints bien diseñados

  • Obtener todos los productos — /productos — Método: GET
  • Obtener producto por id — /productos/15 — Método: GET
  • Crear nuevo producto — /productos — Método: POST
  • Actualizar producto — /productos/15 — Método: PUT
  • Eliminar producto — /productos/15 — Método: DELETE
  • Listar pedidos de un usuario — /usuarios/1/pedidos — Método: GET
  • Buscar usuarios activos — /usuarios?activo=true — Método: GET

8 Buenas prácticas para diseñar rutas

Usar sustantivos, no verbos

  • Correcto: /usuarios
  • Incorrecto: /getUsuarios, /crearUsuario (el método HTTP ya indica la acción).

Usar plural en los recursos: /usuarios, /productos, /pedidos.

Usar jerarquía clara: /usuarios/1/pedidos en lugar de /pedidosDeUsuario/1.

Evitar rutas muy largas

  • Correcto: /productos/15/comentarios
  • Incorrecto: /api/v1/listarTodosLosComentariosDelProducto15

Versionar la API en la ruta base

/api/v1/usuarios
/api/v2/usuarios

Usar minúsculas y guiones medios

  • Correcto: /historial-compras
  • Incorrecto: /HistorialCompras

9 Ejemplo práctico

Supongamos una API de tienda online. Endpoints posibles:

GET    /productos            # lista de productos
GET    /productos/10         # producto con id=10
POST   /productos            # agregar un nuevo producto
PUT    /productos/10         # actualizar producto id=10
DELETE /productos/10         # eliminar producto id=10

GET    /usuarios/5/pedidos   # listar pedidos del usuario con id=5
POST   /usuarios/5/pedidos   # crear pedido para usuario id=5

10 Conclusión del capítulo

Un endpoint es una URL que apunta a un recurso específico en la API. Las rutas deben ser claras, consistentes y jerárquicas.

Usamos Path Parameters para recursos concretos y Query Parameters para filtros. Un buen diseño de endpoints hace que la API sea fácil de usar y mantener.

👉 Recordá: si la ruta se entiende leyendo en voz alta, la API está bien diseñada.

Retornar