Endpoint

Definición

Un endpoint es cada una de las URLs concretas que una API expone para que clientes externos hagan peticiones. Es el "punto de contacto" entre el cliente (una web, una app móvil, otro servidor) y el servicio que provee los datos o ejecuta una acción.

Una API completa suele tener entre 5 y 200 endpoints, cada uno responsable de una operación específica. Por ejemplo, la API de un e-commerce típico podría exponer:

• GET /productos — listar productos
• GET /productos/{id} — leer un producto concreto
• POST /productos — crear un producto nuevo
• POST /pedidos — crear un pedido
• GET /pedidos/{id} — leer un pedido

Cada combinación de método HTTP + URL es un endpoint distinto, aunque la URL sea la misma. GET /productos y POST /productos son endpoints diferentes.

Cómo funciona

Un endpoint vive en un servidor (físico o cloud) que está escuchando peticiones HTTP en una URL pública. Cuando llega una petición:

1. El servidor recibe la petición (método + URL + headers + body opcional)
2. El router del backend identifica qué función maneja ese endpoint concreto
3. Esa función ejecuta la lógica: valida la petición, consulta la base de datos, llama a otros servicios, etc.
4. Devuelve una respuesta estructurada (típicamente JSON) con un código HTTP de estado

Si pides un endpoint que no existe, el servidor responde 404 Not Found. Si pides uno que existe pero no tienes permiso, 401 o 403. Si todo va bien, 200 OK (o 201 si has creado algo nuevo).

Ejemplo práctico

Imagina la API de IMDICA con tres endpoints relacionados:

GET    https://api.imdica.es/v1/productos?categoria=fresas&limit=20
GET    https://api.imdica.es/v1/productos/12345
POST   https://api.imdica.es/v1/productos

Petición real al primero desde la web:

const respuesta = await fetch(
  'https://api.imdica.es/v1/productos?categoria=fresas&limit=20',
  {
    headers: {
      'Authorization': 'Bearer ABC123',
      'Accept': 'application/json'
    }
  }
);

const { productos, total } = await respuesta.json();
// { productos: [...20 items...], total: 87 }

Cada parte de la URL tiene un propósito:

• https://api.imdica.es → dominio del servidor de la API
• /v1 → versión de la API
• /productos → el recurso (en REST, en plural)
• ?categoria=fresas&limit=20 → query params para filtrar/paginar

Anatomía de un buen endpoint

Un endpoint bien diseñado cumple varias cosas:

• URL semántica: la persona que la lee adivina qué hace (/productos/12345/stock, no /api?p=12345&action=getStock)
• Versionado: empieza con /v1, /v2, etc. para que puedas evolucionar sin romper clientes viejos
• Plural para colecciones: /productos (lista), /productos/12345 (uno concreto)
• Idempotente cuando aplica: si haces GET varias veces, el resultado es el mismo
• Documentado: cada endpoint debe tener su spec (OpenAPI/Swagger, Postman, etc.) con request/response esperados

Errores comunes

• Verbos en la URL: /getProducto, /createPedido, /deleteUser. El verbo lo da el método HTTP, no la URL. Esto es un anti-patrón conocido.
• Sin versionado: el día que cambies un campo, romperás todas las apps que dependan del endpoint. Versiona desde el día 1.
• Endpoints en singular vs plural inconsistentes: usa siempre plural (/productos), nunca mezcles /producto/12345 con /productos.
• Endpoints "swiss-army": un único endpoint que hace 10 cosas según los parámetros (/api?action=...) es difícil de documentar, testear y cachear. Divide.
• Olvidar paginación: si GET /productos devuelve todos sin límite, cuando tengas 10.000 productos la respuesta tarda 30 segundos. Pagina siempre (?limit=20&offset=0 o cursor-based).
• Mezclar endpoints públicos y privados en el mismo path: separa /v1/public/... de /v1/private/... para que sea evidente qué requiere autenticación.

Cuándo crear un endpoint nuevo

Crea un endpoint nuevo cuando:

• Hay una operación clara que un cliente externo necesitará hacer repetidamente
• La operación opera sobre un recurso identificable
• El resultado es independiente y tiene sentido por sí mismo

No crees endpoint nuevo cuando:

• Es solo una variante de uno existente con un parámetro distinto → mejor query param
• Es una operación interna que ningún cliente externo va a llamar → función privada, no endpoint público

Referencias

• MDN — Visión general de HTTP
• REST Resource Naming Guide
• OpenAPI Specification — para documentar endpoints