También disponible en inglés

Antes de diseñar un endpoint, clasificá su naturaleza. Recién después elegí su ubicación.

El problema silencioso

Existen muchos artículos que explican cómo escribir una API REST. Aquí, en cambio, nos vamos a centrar en una pregunta previa: ¿cómo decidir dónde debe vivir un endpoint antes de escribirlo?

Cuando ese criterio no existe, la ubicación de cada nuevo endpoint termina dependiendo de la intuición, del precedente o de una negociación entre desarrolladores. El resultado suele ser un árbol de APIs que funciona al principio, pero que se vuelve cada vez más difícil de navegar y mantener.

Los síntomas son conocidos:

• Endpoints casi iguales, creados por equipos distintos.
• Frontends que deben ensamblar múltiples llamadas para una sola pantalla.
• URLs que reflejan el organigrama y no la actividad principal de la organización.
• Convenciones implícitas que solo conocen quienes llevan años en el proyecto.

No suele haber un gran error arquitectónico. Hay cientos de pequeñas decisiones inconsistentes.

La idea central

Este artículo propone un criterio de clasificación previo al diseño del endpoint. La idea es sencilla: antes de pensar la URL, hay que entender qué tipo de necesidad estamos resolviendo.

La tesis que atraviesa todo el texto es:

Antes de diseñar un endpoint, hay que clasificar su naturaleza. Recién después decidir dónde debe vivir.

No se trata de una convención de nombres ni de una discusión más sobre REST. Se trata de un marco de decisión que puede aplicarse independientemente del estilo arquitectónico.

Seis clasificaciones posibles

El framework establece seis categorías. Cada una responde a una naturaleza distinta de endpoint.

Como regla general, cuando un requerimiento parece encajar en más de una clasificación, conviene priorizar la más específica y restrictiva. Estas seis categorías son el mecanismo mediante el cual resolvemos el problema de la falta de criterio.

Dominios Core: la fuente de verdad

Los Dominios Core representan la fuente de verdad de la actividad principal. Contienen operaciones atómicas sobre sus entidades fundamentales. Habitualmente se corresponden con los conceptos centrales que maneja la organización: clientes, pedidos, productos, cuentas, etc.

Ejemplo:

GET /api/v1/ventas/pedidos/{id}
POST /api/v1/ventas/pedidos

Aquí las operaciones son atómicas, afectan a una sola entidad y respetan el principio de que el método HTTP define la acción.

Vistas: desacoplar al consumidor

Las Vistas no existen únicamente para simplificar consultas. Su propósito más valioso es desacoplar al consumidor de la estructura interna de los dominios core.

Una pantalla, un reporte o un sistema externo no deberían necesitar conocer cómo están organizados internamente los dominios. Las Vistas actúan como una capa de desacople: si mañana un dominio se divide o se reorganiza, el consumidor puede seguir utilizando la misma Vista mientras el backend adapta su implementación.

Ejemplo:

GET /api/v1/vistas/resumen-ventas-por-cliente

Ese resumen puede combinar datos de pedidos, pagos y envíos. El frontend recibe exactamente lo que necesita, sin ensamblar llamadas ni conocer la estructura interna.

Procesos: cuando el objetivo es ejecutar, no operar sobre una entidad

La categoría Procesos agrupa endpoints cuya naturaleza no es operar sobre una entidad del dominio core, sino ejecutar una secuencia coordinada de acciones. Puede tratarse de:

• Un cierre mensual
• Una conciliación bancaria
• Una reversión o compensación de una operación compleja
• Un recálculo de saldos
• Una liquidación
• Una sincronización de padrones
• Un proceso batch pesado
• Cualquier otra rutina que no encaje naturalmente en un CRUD de entidad

El nombre "procesos" es intencionalmente amplio. No asume masividad ni cantidad de entidades afectadas. Solo asume que el endpoint existe para poner en marcha un proceso, no para leer o modificar un recurso atómico.

Ejemplos:

POST /api/v1/procesos/cierre-mensual
POST /api/v1/procesos/revertir-operacion/{id}
POST /api/v1/procesos/conciliacion-bancaria

La pregunta que define esta categoría es:

¿El endpoint existe para operar sobre una entidad del dominio core, o para ejecutar un proceso?

Si la respuesta es "proceso", su lugar es /procesos.

Un ejemplo práctico: importar clientes

Supongamos que aparece el siguiente requerimiento:

"El sistema debe permitir importar clientes desde un archivo Excel."

Sin un criterio claro, distintos equipos podrían proponer ubicaciones diferentes para el endpoint:

POST /clientes/importacion
POST /clientes/importar
POST /admin/importacion-clientes
POST /batch/clientes/importacion

Todas las alternativas parecen razonables, pero responden a intuiciones distintas. El resultado es que, con el tiempo, el árbol de APIs termina creciendo de forma inconsistente.

Aplicando el flujo de decisión de este framework:

• ¿Interactúa con un sistema externo? → No.
• ¿Es una lectura que compone múltiples dominios? → No.
• ¿El objetivo es operar sobre una entidad del dominio core? → No. No se está creando, modificando ni consultando un cliente de forma atómica. El endpoint no recibe la representación de un recurso Cliente para operarlo de forma atómica; recibe un archivo binario (Excel) que requiere parsing, validaciones de lote y una lógica de coordinación pesada.
• ¿El objetivo es ejecutar un proceso? → Sí.

Por lo tanto, la clasificación correcta es Procesos, y una ubicación coherente sería:

POST /procesos/importacion-clientes

Lo importante es observar que la decisión no depende de la entidad involucrada, sino de la naturaleza del endpoint. Aunque el proceso trabaje sobre clientes, el endpoint existe para poner en marcha una importación, no para operar sobre el recurso clientes.

Este ejemplo ilustra el objetivo principal del framework: que dos arquitectos distintos, enfrentados al mismo requerimiento, lleguen a la misma decisión siguiendo el mismo razonamiento, en lugar de depender de preferencias personales o convenciones implícitas.

Integraciones, Configuración y Sistema

• Integraciones externas: para invocar sistemas externos (cliente activo). Ejemplo: /integraciones/externos/salesforce/contactos. El contrato lo define el tercero, y eso determina tanto la ubicación como la política de versionado: no es el ciclo de vida interno del sistema el que gobierna esta interfaz.
• Webhooks: para recibir notificaciones desde sistemas externos. Ejemplo: /integraciones/webhooks/paypal/pago-completado. La misma lógica aplica en sentido inverso: es el tercero quien impone la URL que debe exponerse, razón por la cual forzarlo dentro de /api/v1/ sería una convención vacía.
• Configuración: para tablas paramétricas o globales. Ejemplo: /configuracion/impuestos. Estos datos existen como carril separado porque son transversales a varios dominios y no tienen un dueño de dominio claro; meterlos dentro de cualquier dominio core sería una decisión arbitraria.
• Sistema: para operaciones técnicas del propio API. Ejemplo: /sistema/health. La regla de inclusión es la ausencia de semántica de negocio: si el endpoint tiene sentido para el negocio, no pertenece acá.

¿De dónde salen los dominios? APQC y TM Forum

Definir los dominios de alto nivel suele ser un desafío. Inventar una taxonomía propia para cada organización puede llevar a discusiones interminables y a que el árbol termine reflejando el organigrama en lugar de la actividad real.

Para evitarlo, el framework se apoya en taxonomías maduras y ampliamente probadas:

• APQC PCF (Process Classification Framework): ideal para organizaciones con operaciones físicas, logística, manufactura y procesos corporativos tradicionales.
• TM Forum eTOM (enhanced Telecom Operations Map): pensado para organizaciones de servicios digitales, telecomunicaciones, plataformas y suscripciones.

Apoyarse en estos modelos no es un detalle secundario. Es una de las mayores fortalezas del enfoque, porque reduce discusiones de nomenclatura y hace que el árbol refleje la realidad operativa.

A modo de ilustración, algunos ejemplos de cómo se traducen estas taxonomías a URLs concretas:

En catálogo se encuentran los árboles de contexto detallados basados en APQC PCF y TM Forum eTOM, con una lista mucho más extensa de dominios y recursos.

Regla: APQC y TM Forum solo se utilizan para estructurar los dominios core. Las demás categorías son transversales y no siguen ninguna taxonomía de negocio, porque su naturaleza no es operar sobre entidades del dominio.

Flujo de decisión

Para aplicar la clasificación en el día a día, conviene seguir un flujo de decisión práctico:

¿Interactúa con un sistema externo?
│
├── Sí → ¿Es una llamada activa o un webhook?
│         ├── Llamada activa → /integraciones/externos/{sistema}
│         └── Webhook → /integraciones/webhooks/{origen}/{evento}
│
└── No → ¿Es una lectura que compone múltiples dominios?
         │
         ├── Sí → /vistas/{nombre}
         │
         └── No → ¿El objetivo es operar sobre una entidad del dominio core?
                  │
                  ├── Sí → /{dominio}/{recurso}
                  │
                  └── No → ¿El objetivo es ejecutar un proceso?
                           │
                           ├── Sí → /procesos/{nombre}
                           │
                           └── No → ¿Es configuración global?
                                    │
                                    ├── Sí → /configuracion/{tabla}
                                    │
                                    └── No → /sistema/{operacion}

Este árbol no es un dogma. Es una herramienta práctica que ayuda a mantener consistencia cuando distintos equipos o personas diseñan nuevos endpoints.

Algunas convenciones útiles

Más allá de la clasificación, hay buenas prácticas que conviene adoptar:

• Usar kebab-case en toda la URL (ejemplo: procesos/cierre-mensual).
• Evitar verbos en la ruta; la acción la define el método HTTP.
• Mantener una semántica uniforme para los identificadores.

Sobre el prefijo /api

El prefijo /api se utiliza para separar los endpoints de la interfaz programática de otros recursos del servidor (archivos estáticos, páginas administrativas, etc.). No es obligatorio, pero es una práctica ampliamente extendida que permite aplicar políticas específicas (autenticación, rate limiting, logging) sobre todo el árbol de la API de forma consistente. En este artículo se asume su uso, pero cada organización puede decidir si lo incluye o no.

Sobre el versionado

La convención /api/v1/ al inicio de la URL es útil cuando todos los endpoints de una categoría comparten el mismo ciclo de vida. Esto aplica naturalmente a Dominios Core y Vistas.

Sin embargo, otras categorías responden a contratos cuyo propietario y evolución son externos al sistema. Por ejemplo:

• Un webhook de PayPal o Stripe impone la URL que debe exponerse. No tiene sentido forzarlo dentro de /api/v1/.
• Una integración activa con Salesforce puede necesitar su propio versionado, por ejemplo /integraciones/externos/salesforce/v2/..., independiente del versionado global.

Regla general: el prefijo /api/v1/ no debe aplicarse mecánicamente a todas las categorías. Cada clasificación puede definir su política de versionado según su naturaleza. Para integraciones y webhooks, la estrategia de versionado se deriva del contrato que gobierna esa interfaz, no necesariamente del versionado global de la API.

Para cerrar

Una buena arquitectura de APIs no consiste en encontrar un lugar para cada endpoint. Consiste en tener un criterio que haga evidente cuál es ese lugar antes de escribirlo.

Cuando dos arquitectos distintos llegan a la misma decisión siguiendo el mismo razonamiento, el árbol deja de depender de la intuición y pasa a formar parte de la arquitectura del sistema. Las discusiones sobre dónde colocar un nuevo endpoint se vuelven rápidas, predecibles y fundamentadas.

Este trabajo pretende ser un punto de partida. Más que establecer reglas inmutables, busca proponer un criterio de clasificación que pueda enriquecerse con la experiencia y el debate de la comunidad. Ningún framework sobrevive sin evolución, y este tampoco.

Nota final: la propuesta de las seis clasificaciones y el flujo de decisión es abierta. Si tu organización encuentra que una categoría adicional o una variante funciona mejor, el principio fundamental —clasificar antes de diseñar— sigue siendo lo que realmente importa.