Catalogo de Endpoints (SLA, idempotencia y límites)

Este catálogo complementa OpenAPI con reglas operativas que deben respetar frontend, backend y QA.

1. Convenciones operativas

• timeout_ms: tiempo máximo de respuesta del endpoint.
• retries: solo aplica a llamadas internas entre servicios, nunca para mutaciones no idempotentes sin llave.
• idempotency_key: obligatorio en operaciones de creación de alto impacto (appointments, payments, notifications/send).
• error_budget: porcentaje mensual permitido de errores 5xx + timeouts.

2. Endpoints críticos por módulo

Módulo	Método + Ruta	Owner	Idempotencia	Rate limit	timeout_ms	retries internos	SLO p95	Error budget
Auth	POST /api/v1/auth/login	auth-service	No (credenciales)	10 req/5 min por IP+email	1200	0	< 300ms	0.5%
Auth	POST /api/v1/auth/refresh	auth-service	Sí (rotación controlada)	30 req/10 min por sesión	800	0	< 200ms	0.5%
Auth	POST /api/v1/auth/logout	auth-service	Sí	60 req/10 min por sesión	800	0	< 200ms	0.5%
Registro	POST /api/v1/auth/register	auth-service	Sí (Idempotency-Key)	5 req/15 min por email	1500	0	< 400ms	1.0%
Registro	POST /api/v1/auth/token/verify	auth-service	Sí (token hash + nonce)	5 req/15 min por email	1000	0	< 350ms	1.0%
Catálogos	GET /api/v1/meta/countries	catalog-service	N/A (read)	120 req/min por IP	900	1	< 250ms	1.0%
Catálogos	POST /api/v1/admin/catalogs/geo/countries	catalog-service	Sí (Idempotency-Key)	20 req/min por admin	1200	0	< 350ms	1.0%
Búsqueda	GET /api/v1/search/doctors	search-service	N/A (read)	100 req/min por IP	1000	1	< 300ms	1.0%
Búsqueda	GET /api/v1/search/entities	search-service	N/A (read)	100 req/min por IP	1000	1	< 300ms	1.0%
Agenda	POST /api/v1/appointments	appointments-service	Sí (Idempotency-Key)	20 req/min por usuario	1500	0	< 400ms	1.0%
Agenda	PATCH /api/v1/appointments/{id}	appointments-service	Sí (If-Match/version)	30 req/min por usuario	1200	0	< 400ms	1.0%
Disponibilidad	GET /api/v1/availability	availability-service	N/A (read)	120 req/min por IP	1000	1	< 300ms	1.0%
Notificaciones	POST /api/v1/notifications/send	notification-service	Sí (Idempotency-Key)	30 req/min por servicio	1200	2	< 2000ms	1.5%
Reseñas	POST /api/v1/reviews	review-service	Sí (Idempotency-Key)	10 req/min por usuario	1200	0	< 500ms	1.0%
Cupones	POST /api/v1/professional/coupons	promotions-service	Sí (Idempotency-Key)	20 req/min por owner	1200	0	< 500ms	1.0%

3. Reglas de implementación

1. Todo endpoint POST de creación debe documentar explícitamente si requiere Idempotency-Key.
2. Mutaciones críticas deben responder 409 cuando detecten duplicidad semántica.
3. Las respuestas deben incluir trace_id para correlación observabilidad.
4. Rate limit debe estar en gateway/API layer y reflejarse en Swagger (429 + ejemplo).
5. QA debe validar límites y timeouts en pruebas de carga controlada.

4. Checklist de adopción

• OpenAPI contiene 429 y ejemplo de respuesta por endpoint crítico.
• Endpoints de mutación crítica validan idempotencia.
• Dashboard de SLO incluye p95 y error budget por módulo.
• Runbook de incidentes referencia este catálogo para diagnóstico.