¿Qué es un endpoint de API? Definición, ejemplos y buenas prácticas

¿Qué es un endpoint de API?

Un endpoint de API (o punto de conexión) es la dirección a la que llama un cliente para usar una operación concreta de una API: una ruta URL combinada con un método HTTP, como GET /users/42 para leer un usuario o POST /users para crear uno. La misma ruta con otro método es otro endpoint. Todos los endpoints juntos forman la superficie de la API.

Las APIs REST exponen muchos endpoints, normalmente uno por recurso y operación. GraphQL suele exponer un único endpoint (a menudo /graphql) y el cliente describe en la petición los datos que quiere. gRPC nombra las operaciones como métodos de un servicio en lugar de rutas URL.

Cómo funciona un endpoint de API

Un endpoint REST tiene tres partes:

• URL base. Protocolo, host y un prefijo opcional, por ejemplo https://api.example.com.
• Ruta. El camino hasta un recurso, por ejemplo /users/42. Los parámetros de consulta, como ?page=2&limit=20, la afinan.
• Método HTTP. El verbo que elige la operación: GET, POST, PUT, PATCH o DELETE.

Una llamada completa a un endpoint de "crear usuario" y su respuesta:

POST https://api.example.com/users
Content-Type: application/json
Authorization: Bearer <token>

{ "name": "Alice", "email": "alice@example.com" }

HTTP/1.1 201 Created
Location: /users/43

El método importa más allá del nombre. Según MDN, solo GET es seguro (no cambia nada en el servidor), y GET, PUT y DELETE son idempotentes: repetir la petición tiene el mismo efecto que enviarla una vez. POST y PATCH no lo son, por eso reintentarlos exige cuidado: consulta idempotencia.

Patrones habituales de endpoints

Reglas de diseño que funcionan

• Sustantivos en la ruta, verbos en el método. /users, no /getUsers.
• Un solo estilo de nombres. Plural o singular, kebab-case o snake_case: elige uno y úsalo en todas partes.
• Rutas que muestran relaciones. /users/42/orders se lee como "los pedidos del usuario 42".
• Códigos de estado reales. 201 tras crear, 204 para un éxito sin contenido, 400 para una petición incorrecta, 401 si el cliente no está autenticado, 403 si no tiene permiso, 404 si no hay nada, 429 por demasiadas peticiones, 5xx para fallos del servidor (MDN, según RFC 9110).
• Paginación y filtros en la query string. /users?role=admin&page=2.
• Versiones explícitas. /v1/users permite publicar cambios incompatibles como /v2.
• Una especificación legible por máquinas. Describe cada endpoint en OpenAPI, como se explica en Qué es Swagger.

Errores comunes en endpoints

• Acciones en la ruta. POST /createUser y ?action=delete van contra la semántica de los métodos. Usa POST /users y DELETE /users/42.
• HTTP 200 con el error en el cuerpo. Clientes, cachés y monitores leen primero el código de estado. Devuelve 4xx o 5xx cuando algo falla.
• Secretos en la URL. Tokens y datos personales en la ruta o la query string acaban en logs, historial del navegador y cabeceras Referer. Envíalos en cabeceras o en el cuerpo.
• Formato de error inconsistente. Si un endpoint devuelve {"error": ...} y otro {"message": ...}, cada cliente necesita casos especiales.
• Sin comprobar la autorización en cada endpoint. La autenticación dice quién llama. Cada endpoint debe comprobar además qué puede hacer esa persona.
• Sin límite de peticiones. Un endpoint sin límite es el primero en caer ante un abuso o una tormenta de reintentos. Responde con 429 y una cabecera Retry-After. Contexto: causas del rate limiting en APIs (artículo en inglés).

Probar y monitorizar endpoints de API

Cada endpoint se puede verificar en varios niveles. Las pruebas de API comprueban que devuelve los datos y el estado correctos. Las pruebas de carga muestran cómo responde cuando muchos clientes lo llaman a la vez; LoadFocus ejecuta pruebas JMeter y k6 desde 25 regiones en la nube, y el plan gratuito incluye hasta 10 usuarios virtuales. Con el endpoint en producción, la monitorización de APIs lo llama de forma programada y comprueba código de estado, cuerpo, cabeceras y tiempo de respuesta, de modo que un 200 con datos incorrectos también falla; el plan gratuito comprueba cada 5 minutos. Para echar un vistazo puntual a una URL pública, el verificador de estado de API envía una petición desde seis regiones sin registro. Las causas típicas de endpoints lentos están en Common API performance issues and how to detect them (en inglés), y la parte de vigilancia en Qué es la monitorización de APIs.

Preguntas frecuentes sobre endpoints de API

¿Qué diferencia hay entre una API y un endpoint de API?

La API es toda la interfaz: todos los endpoints junto con sus esquemas, autenticación y formatos de error. Un endpoint es una operación concreta dentro de ella, por ejemplo la llamada para crear un cobro en una API de pagos.

¿GET /users y POST /users son el mismo endpoint?

No. Comparten la ruta pero usan métodos distintos, así que son dos endpoints: uno lista usuarios y el otro crea uno.

¿Un endpoint es lo mismo que una URL?

No exactamente. La URL es solo la dirección. El endpoint es la URL más el método HTTP, porque el método decide qué hace el servidor.

¿Cuántos endpoints debería tener una API?

Los que necesite su alcance. Una API pequeña y enfocada puede tener unos pocos, una API de plataforma grande, cientos. El número no mide la calidad; la coherencia y una buena documentación sí.

¿En qué se diferencian los endpoints de REST y de GraphQL?

REST reparte las operaciones en muchos endpoints, uno por recurso y método. GraphQL suele tener uno solo, y la consulta de la petición indica qué campos devolver.

¿Cómo cambio un endpoint sin romper a los clientes?

Añade una versión a la ruta (/v1/users, /v2/users), mantén ambas durante la transición, anuncia una fecha de retirada para la antigua y documenta qué cambió.