DEV Community: Edgardo Genini

[ES] Cómo organizar el árbol de APIs REST para que sobreviva al tiempo (y a los cambios de organigrama)

Edgardo Genini — Tue, 16 Jun 2026 19:29:10 +0000

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.

Clasificación	Ubicación sugerida
Dominio Core	`/{dominio}/{recurso}`
Vista	`/vistas/{nombre}`
Integración	`/integraciones/externos/...` y `/integraciones/webhooks/...`
Procesos	`/procesos/{nombre}`
Configuración	`/configuracion/{tabla}`
Sistema	`/sistema/{operacion}`

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:

Taxonomía	Ejemplos de dominios y recursos
APQC	`/finanzas/cuentas-contables` `/logistica/inventarios` `/comercial/oportunidades`
TM Forum	`/cliente/abonados` `/operaciones/facturacion` `/recursos/licencias`

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.

Catálogo de Árboles de Contexto: Estándares de Referencia

Edgardo Genini — Tue, 16 Jun 2026 19:27:51 +0000

A fin de evitar deducciones en el día a día, se exponen los dos árboles oficiales basados en taxonomías internacionales para estructurar los Niveles 1 y 2 de los Dominios Core.

Árbol A: Taxonomía Corporativa Universal (Base APQC PCF)

Recomendado para flujos de gestión tradicional, operaciones lineales, logística física y entornos administrativos pesados. Cubre fielmente las 13 categorías de procesos del Cross-Industry Framework de APQC.

Es posible que en algunas ramas se puedan interpretar como procesos, vistas, etc, siempre es necesario ir al flujo de decisión para saber dónde corresponde, cualquiera de estas ramas podría contener un dominio core, pero también un proceso, vista, etc, en esos casos se agrega la rama en procesos, vistasm, etc para mantener cada servcio en su categoría
No se eliminan para que no dar la idea de que no está por error.

/api/estrategia (Cat. 1: Develop Vision and Strategy)
- /objetivos-corporativos
- /planificacion-estrategica
- /indicadores-macro
/api/producto (Cat. 2: Develop and Manage Products and Services)
- /productos
- /tarifas
- /ciclo-vida (Gestión de versiones, lanzamiento y retiro)
/api/comercial (Cat. 3: Market and Sell Products and Services)
- /prospectos
- /oportunidades
- /acuerdos-comerciales
- /campanas
/api/cadena-suministro (Cat. 4: Deliver Services / Manage Supply Chain)
- /ordenes-compra
- /inventarios
- /depositos
- /despachos
- /proveedores (Gestión de la relación y desempeño)
/api/atencion-cliente (Cat. 5: Manage Customer Service)
- /solicitudes-servicio
- /devoluciones
- /satisfaccion
/api/capital-humano (Cat. 6: Develop and Manage Human Capital)
- /empleados
- /contratos-laborales
- /liquidaciones
- /desempeno
- /capacitacion
/api/tecnologia (Cat. 7: Manage Information Technology)
- /activos-ti
- /servicios-informaticos
- /seguridad-informatica
/api/finanzas (Cat. 8: Manage Financial Resources)
- /cuentas-corrientes
- /asientos-contables
- /comprobantes-fiscales
- /flujos-caja
- /presupuestos
/api/activos (Cat. 9: Acquire, Construct, and Manage Assets)
- /inmuebles
- /maquinaria-equipos
- /mantenimiento
/api/legal-compliance (Cat. 10: Manage Enterprise Risk, Compliance, Remediation, and Resiliency)
- /auditorias-normativas
- /declaraciones-juradas
- /contratos-legales
- /gestion-riesgos
- /continuidad-negocio
/api/relaciones-externas (Cat. 11: Manage External Relationships)
- /relaciones-institucionales
- /responsabilidad-social
/api/capacidades (Cat. 12: Develop and Manage Business Capabilities)
- /arquitectura-empresarial
- /gestion-proyectos (PMO)
/api/conocimiento (Cat. 13: Develop and Manage Knowledge, Improvement, and Change)
- /gestion-cambios
- /mejora-continua
- /documentacion

Árbol B: Arquitectura de Ciclo de Servicio (Ingeniería TM Forum / eTOM)

Recomendado para modelos basados en suscripciones, activos intangibles, plataformas SaaS, aprovisionamiento automatizado e infraestructura lógica. Se enfoca exclusivamente en el núcleo distintivo de eTOM (FAB, Partes, Servicios y Recursos), evitando solapamientos con la gestión corporativa genérica del Árbol A.

/api/partes (Party Management: Dominio unificado distinguiendo roles)
- /clientes (Entidad que contrata y paga)
- /usuarios (Entidad que consume el servicio, ej. empleado de un cliente B2B)
- /socios-comerciales (Partners B2B2X)
- /acuerdos-nivel-servicio (SLAs contractuales vinculados a la parte)
/api/servicios (Service Management: Capa intermedia entre Cliente y Recurso)
- /catalogo-servicios (Definición comercial y técnica de lo que se vende)
- /inventario-servicios (Instancias de servicios activos y asignados)
- /configuraciones (Parámetros específicos de cada instancia)
/api/realizacion (Fulfillment: Flujo completo de entrega)
- /ordenes-servicio (Ciclo de vida de la orden: crear, validar, descomponer)
- /calificacion (Service Qualification: validar viabilidad técnica antes de vender)
- /aprovisionamiento (Activación lógica y despliegue de recursos)
/api/garantia (Assurance: Operación y soporte proactivo/reactivo)
- /incidentes (Gestión de fallas reportadas)
- /alarmas (Eventos proactivos detectados desde la red/plataforma)
- /telemetria (Métricas de calidad en tiempo real)
- /gestion-sla (Monitoreo y penalización por incumplimiento)
- /problemas (Gestión de causa raíz de incidentes recurrentes)
/api/facturacion (Billing / Revenue Management)
- /tasacion (Rating: cálculo del costo basado en el uso en tiempo real)
- /ciclos-cobro (Generación de facturas recurrentes)
- /conciliacion (Cruce de datos de uso vs. datos facturados)
- /gestion-cobranza (Manejo de morosidad y disputas)
/api/recursos (Resource Management: Inventario lógico/de red, aislado de TI corporativa)
- /inventario-red (Topología y elementos de red lógicos/físicos)
- /direcciones-ip
- /licencias
- /instancias-servidor
- /capacidad (Gestión de umbrales y disponibilidad antes del agotamiento)

[EN] How to Organize a REST API Tree to Survive Time (and Org Chart Changes)

Edgardo Genini — Tue, 16 Jun 2026 19:25:11 +0000

Also available in Spanish

Before designing an endpoint, classify its nature. Only then choose its location.

The Silent Problem

There are many articles explaining how to write a REST API. Here, instead, we will focus on a prior question: how to decide where an endpoint should live before writing it?

When that criterion does not exist, the placement of each new endpoint ends up depending on intuition, precedent, or negotiation among developers. The result is usually an API tree that works at first, but becomes increasingly difficult to navigate and maintain.

The symptoms are well known:

Nearly identical endpoints, created by different teams.
Frontends that must assemble multiple calls for a single screen.
URLs that reflect the org chart rather than the organization's core activity.
Implicit conventions known only to those who have been on the project for years.

There is usually no grand architectural mistake. There are hundreds of small, inconsistent decisions.

The Central Idea

This article proposes a pre-design classification criterion. The idea is simple: before thinking about the URL, you must understand what type of need you are solving.

The thesis that runs through the entire text is:

Before designing an endpoint, classify its nature. Only then decide where it should live.

This is not about naming conventions or yet another REST discussion. It is about a decision framework that can be applied regardless of architectural style.

Six Possible Classifications

The framework establishes six categories. Each one responds to a different endpoint nature.

Classification	Suggested Location
Core Domain	`/{domain}/{resource}`
View	`/views/{name}`
Integration	`/integrations/external/...` and `/integrations/webhooks/...`
Process	`/processes/{name}`
Configuration	`/configuration/{table}`
System	`/system/{operation}`

As a general rule, when a requirement seems to fit more than one classification, it is best to prioritize the most specific and restrictive one. These six categories are the mechanism through which we solve the lack-of-criterion problem.

Core Domains: The Source of Truth

Core Domains represent the source of truth for the main activity. They contain atomic operations on their fundamental entities. They usually correspond to the central concepts managed by the organization: customers, orders, products, accounts, etc.

Example:

GET /api/v1/sales/orders/{id}
POST /api/v1/sales/orders

Here the operations are atomic, affect a single entity, and respect the principle that the HTTP method defines the action.

Views: Decouple the Consumer

Views do not exist solely to simplify queries. Their most valuable purpose is to decouple the consumer from the internal structure of the core domains.

A screen, a report, or an external system should not need to know how the core domains are organized internally. Views act as a decoupling layer: if tomorrow a domain is split or reorganized, the consumer can continue using the same View while the backend adapts its implementation.

Example:

GET /api/v1/views/sales-summary-by-customer

That summary may combine data from orders, payments, and shipments. The frontend receives exactly what it needs, without assembling calls or knowing the internal structure.

Processes: When the Goal Is to Execute, Not to Operate on an Entity

The Processes category groups endpoints whose nature is not to operate on a core domain entity, but to execute a coordinated sequence of actions. This may include:

A month-end close
A bank reconciliation
A reversal or compensation of a complex operation
A balance recalculation
A settlement
A registry synchronization
A heavy batch process
Any other routine that does not naturally fit into an entity CRUD

The name "processes" is intentionally broad. It does not assume massiveness or the number of entities affected. It only assumes that the endpoint exists to trigger a process, not to read or modify an atomic resource.

Examples:

POST /api/v1/processes/month-end-close
POST /api/v1/processes/reverse-operation/{id}
POST /api/v1/processes/bank-reconciliation

The question that defines this category is:

Does the endpoint exist to operate on a core domain entity, or to execute a process?

If the answer is "process," its place is /processes.

A Practical Example: Importing Customers

Suppose the following requirement appears:

"The system must allow importing customers from an Excel file."

Without a clear criterion, different teams might propose different locations for the endpoint:

POST /customers/import
POST /customers/import
POST /admin/customer-import
POST /batch/customers/import

All alternatives seem reasonable, but they respond to different intuitions. The result is that, over time, the API tree ends up growing inconsistently.

Applying this framework's decision flow:

Does it interact with an external system? → No.
Is it a read that composes multiple domains? → No.
Is the goal to operate on a core domain entity? → No. It is not creating, modifying, or querying a customer atomically. The endpoint does not receive a representation of a Customer resource to operate on it atomically; it receives a binary file (Excel) that requires parsing, batch validations, and heavy coordination logic.
Is the goal to execute a process? → Yes.

Therefore, the correct classification is Processes, and a coherent location would be:

POST /processes/customer-import

The important thing to observe is that the decision does not depend on the entity involved, but on the nature of the endpoint. Even though the process works on customers, the endpoint exists to trigger an import, not to operate on the customers resource.

This example illustrates the main goal of the framework: that two different architects, faced with the same requirement, reach the same decision by following the same reasoning, instead of depending on personal preferences or implicit conventions.

Integrations, Configuration, and System

External Integrations: to invoke external systems (active client). Example: /integrations/external/salesforce/contacts. The contract is defined by the third party, and that determines both the location and the versioning policy: it is not the system's internal lifecycle that governs this interface.
Webhooks: to receive notifications from external systems. Example: /integrations/webhooks/paypal/payment-completed. The same logic applies in reverse: it is the third party that imposes the URL that must be exposed, which is why forcing it inside /api/v1/ would be an empty convention.
Configuration: for parametric or global tables. Example: /configuration/taxes. These data exist as a separate lane because they are cross-cutting across multiple domains and do not have a clear domain owner; placing them inside any core domain would be an arbitrary decision.
System: for technical operations of the API itself. Example: /system/health. The inclusion rule is the absence of business semantics: if the endpoint makes sense to the business, it does not belong here.

Where Do Domains Come From? APQC and TM Forum

Defining high-level domains is usually a challenge. Inventing a proprietary taxonomy for each organization can lead to endless discussions and a tree that ends up reflecting the org chart rather than the actual activity.

To avoid this, the framework relies on mature and widely tested taxonomies:

APQC PCF (Process Classification Framework): ideal for organizations with physical operations, logistics, manufacturing, and traditional corporate processes.
TM Forum eTOM (enhanced Telecom Operations Map): designed for digital services organizations, telecommunications, platforms, and subscriptions.

Relying on these models is not a secondary detail. It is one of the greatest strengths of the approach, because it reduces naming discussions and makes the tree reflect operational reality.

By way of illustration, some examples of how these taxonomies translate into concrete URLs:

Taxonomy	Examples of Domains and Resources
APQC	`/finance/chart-of-accounts` `/logistics/inventories` `/sales/opportunities`
TM Forum	`/customer/subscribers` `/operations/billing` `/resources/licenses`

In the catalog available at you will find the detailed context trees based on APQC PCF and TM Forum eTOM, with a much more extensive list of domains and resources.

Rule: APQC and TM Forum are only used to structure the core domains. The other categories are cross-cutting and do not follow any business taxonomy, because their nature is not to operate on domain entities.

Decision Flow

To apply the classification in day-to-day work, it is useful to follow a practical decision flow:

Does it interact with an external system?
│
├── Yes → Is it an active call or a webhook?
│         ├── Active call → /integrations/external/{system}
│         └── Webhook → /integrations/webhooks/{source}/{event}
│
└── No → Is it a read that composes multiple domains?
         │
         ├── Yes → /views/{name}
         │
         └── No → Is the goal to operate on a core domain entity?
                  │
                  ├── Yes → /{domain}/{resource}
                  │
                  └── No → Is the goal to execute a process?
                           │
                           ├── Yes → /processes/{name}
                           │
                           └── No → Is it global configuration?
                                    │
                                    ├── Yes → /configuration/{table}
                                    │
                                    └── No → /system/{operation}

This tree is not dogma. It is a practical tool that helps maintain consistency when different teams or people design new endpoints.

Some Useful Conventions

Beyond classification, there are good practices worth adopting:

Use kebab-case throughout the URL (example: processes/month-end-close).
Avoid verbs in the path; the action is defined by the HTTP method.
Maintain uniform semantics for identifiers.

On the /api prefix

The /api prefix is used to separate programmatic interface endpoints from other server resources (static files, admin pages, etc.). It is not mandatory, but it is a widely adopted practice that allows applying specific policies (authentication, rate limiting, logging) over the entire API tree consistently. This article assumes its use, but each organization can decide whether to include it or not.

On Versioning

The /api/v1/ convention at the beginning of the URL is useful when all endpoints in a category share the same lifecycle. This naturally applies to Core Domains and Views.

However, other categories respond to contracts whose owner and evolution are external to the system. For example:

A PayPal or Stripe webhook imposes the URL that must be exposed. It makes no sense to force it inside /api/v1/.
An active integration with Salesforce may need its own versioning, for example /integrations/external/salesforce/v2/..., independent of the global versioning.

General rule: the /api/v1/ prefix should not be applied mechanically to all categories. Each classification may define its versioning policy according to its nature. For integrations and webhooks, the versioning strategy derives from the contract that governs that interface, not necessarily from the global API versioning.

To Close

A good API architecture is not about finding a place for every endpoint. It is about having a criterion that makes that place obvious before writing it.

When two different architects reach the same decision by following the same reasoning, the tree stops depending on intuition and becomes part of the system's architecture. Discussions about where to place a new endpoint become fast, predictable, and grounded.

This work is intended as a starting point. Rather than establishing immutable rules, it seeks to propose a classification criterion that can be enriched by the community's experience and debate. No framework survives without evolution, and neither will this one.

Final note: the proposal of the six classifications and the decision flow is open. If your organization finds that an additional category or a variant works better, the fundamental principle —classify before designing— remains what really matters.

Context Tree Catalog: Reference Standards

Edgardo Genini — Tue, 16 Jun 2026 19:19:52 +0000

In order to avoid deductions in day-to-day operations, the two official trees based on international taxonomies are presented to structure Levels 1 and 2 of the Core Domains.

Tree A: Universal Corporate Taxonomy (APQC PCF Based)
Recommended for traditional management flows, linear operations, physical logistics, and heavy administrative environments. It faithfully covers the 13 process categories of the APQC Cross-Industry Framework.
It is possible that in some branches they can be interpreted as processes, views, etc.; it is always necessary to refer to the decision flow to determine where they belong. Any of these branches could contain a core domain, but also a process, view, etc. In those cases, the branch is added to processes, views, etc., to keep each service in its category.
They are not deleted so as not to give the impression that they are missing by mistake.

/api/strategy (Cat. 1: Develop Vision and Strategy)
/corporate-objectives
/strategic-planning
/macro-indicators

/api/products (Cat. 2: Develop and Manage Products and Services)
/products
/rates
/lifecycle (Version management, launch, and retirement)

/api/commercial (Cat. 3: Market and Sell Products and Services)
/prospects
/opportunities
/commercial-agreements
/campaigns

/api/supply-chain (Cat. 4: Deliver Services / Manage Supply Chain)
/purchase-orders
/inventories
/warehouses
/shipments
/suppliers (Supplier relationship and performance management)

/api/customer-service (Cat. 5: Manage Customer Service)
/service-requests
/returns
/satisfaction

/api/human-capital (Cat. 6: Develop and Manage Human Capital)
/employees
/employment-contracts
/payroll
/performance
/training

/api/technology (Cat. 7: Manage Information Technology)
/it-assets
/it-services
/information-security

/api/finance (Cat. 8: Manage Financial Resources)
/current-accounts
/journal-entries
/tax-receipts
/cash-flows
/budgets

/api/assets (Cat. 9: Acquire, Construct, and Manage Assets)
/real-estate
/machinery-and-equipment
/maintenance

/api/legal-compliance (Cat. 10: Manage Enterprise Risk, Compliance, Remediation, and Resiliency)
/regulatory-audits
/sworn-declarations
/legal-contracts
/risk-management
/business-continuity

/api/external-relations (Cat. 11: Manage External Relationships)
/institutional-relations
/social-responsibility

/api/capabilities (Cat. 12: Develop and Manage Business Capabilities)
/enterprise-architecture
/project-management (PMO)

/api/knowledge (Cat. 13: Develop and Manage Knowledge, Improvement, and Change)
/change-management
/continuous-improvement
/documentation

Tree B: Service Lifecycle Architecture (TM Forum / eTOM Engineering)
Recommended for subscription-based models, intangible assets, SaaS platforms, automated provisioning, and logical infrastructure. It focuses exclusively on the distinctive core of eTOM (FAB, Party, Service, and Resource), avoiding overlaps with the generic corporate management of Tree A.

/api/parties (Party Management: Unified domain distinguishing roles)
/customers (Entity that contracts and pays)
/users (Entity that consumes the service, e.g., employee of a B2B customer)
/partners (B2B2X Partners)
/slas (Contractual SLAs linked to the party)

/api/services (Service Management: Intermediate layer between Customer and Resource)
/service-catalog (Commercial and technical definition of what is sold)
/service-inventory (Active and assigned service instances)
/configurations (Specific parameters for each instance)

/api/fulfillment (Fulfillment: Complete delivery flow)
/service-orders (Order lifecycle: create, validate, decompose)
/qualification (Service Qualification: validate technical feasibility before selling)
/provisioning (Logical activation and resource deployment)

/api/assurance (Assurance: Proactive/reactive operation and support)
/incidents (Reported fault management)
/alarms (Proactive events detected from the network/platform)
/telemetry (Real-time quality metrics)
/sla-management (Monitoring and penalty for non-compliance)
/problems (Root cause management of recurring incidents)

/api/billing (Billing / Revenue Management)
/rating (Rating: calculation of cost based on real-time usage)
/billing-cycles (Generation of recurring invoices)
/reconciliation (Cross-check of usage data vs. billed data)
/collections (Handling of delinquency and disputes)

/api/resources (Resource Management: Logical/network inventory, isolated from corporate IT)
/network-inventory (Logical/physical network topology and elements)
/ip-addresses
/licenses
/server-instances
/capacity (Threshold and availability management before exhaustion)

[EN] Delegated Resource Identifier (DRI): a pattern for persistent references in microservices

Edgardo Genini — Wed, 13 May 2026 01:39:17 +0000

Also available in Spanish

If you've ever stored a URL in a database and later regretted it, this is for you.

It's a familiar scenario: a service needs to keep a reference to a resource that lives in another service. The obvious solution is to store the URL. It works — until the host changes, the API gets a new version, or the team decides to restructure the paths. Suddenly all the stored references are broken, and tracking down the impact becomes a bigger problem than it should be.

The root issue is that a URL mixes two different things: what the resource is and where it lives. When you store a URL, you're betting that location won't change. In systems that evolve, that's usually a losing bet.

The idea

What if instead of storing where the resource lives, you store your own identifier that a gateway knows how to resolve?

commerce:orders/order:id=ARG-2024-00091872
finance:accounts/customer:status:id=109234
health:coverage/credential:patient-id=12345678

Whoever stores the reference doesn't need to know where the resource lives or how to access it. That's the gateway's responsibility. If the API changes, if the service migrates, if a new system appears: only the resolver changes. The stored references remain valid.

I called this scheme Delegated Resource Identifier (DRI).

What this pattern is not

It's not a standard
It requires a gateway as intermediary: it doesn't apply when the client needs to access the resource directly without going through any intermediary
It doesn't impose a context taxonomy: each team defines their own

It's a useful convention when you need persistent references to resources in a controlled ecosystem and want to centralize the resolution logic.

How it's built

The identifier has two parts separated by /:

<context>/<resource>

Context (left side): identifies the domain that knows how to resolve this type of resource. The gateway uses it for routing.
Resource (right side): identifies the concrete resource. Its structure is defined by whoever implements the resolver.

commerce:orders/order:id=ARG-2024-00091872
└─── routing ───┘└─── concrete resource ──┘

: separates hierarchical levels. = assigns values. Each side defines its own internal convention.

The identifier is built by whoever stores the reference, from the data they already have and the context they know. No external call required. A billing service that receives an order ID knows it belongs to commerce:orders and builds the DRI when persisting the reference.

The context can be omitted if the gateway has a default resolver:

/order:id=ARG-2024-00091872

Some use cases

E-commerce: retrieving an order

A customer service system stores references to orders that can come from different channels: own store, marketplace, mobile app. Each channel has its own API.

commerce:orders/order:id=ARG-2024-00091872
commerce:orders/order:id=MKT-2024-00034521

The commerce:orders resolver determines which channel each order belongs to based on the ID prefix and routes to the corresponding API. The identifier remains stable even if the channel's API changes.

Fintech: customer account status

A bank with legacy and modern systems running side by side. The resolver determines which system the customer lives in based on the ID value: customers with id < 50000 are in the legacy system, the rest in the modern one.

finance:accounts/customer:status:id=109234
finance:accounts/customer:status:id=002871

The resolver also encapsulates the decision of which API version to use. And here something interesting emerges: the DRI has two moments in its lifecycle. When persisted, it's just the identifier. When used for a query, it can be enriched with additional context using the same syntax:

finance:accounts/customer:status:id=109234:date=20260101

The resolver can use that date to determine which API version applies. The persisted DRI doesn't change; the additional context is added at query time.

Health: member coverage credential

A member's coverage can change over time: provider migration, gaps in coverage, or coverage with more than one provider. Storing the provider as a fixed value would produce outdated references.

health:coverage/credential:patient-id=12345678

The resolver applies a fallback strategy: it queries the first available provider and if the credential isn't found, tries the next one. The DRI resolves at query time, always reflecting the current state.

Multinational with tenant: supplier by legal entity

A SaaS platform used by a company operating in multiple countries. Each country has its own supplier management system, its own API, and its own tax identifier format.

tenant:acme:ar/supplier:cuit=20123456789
tenant:acme:cl/supplier:rut=76354921-5
tenant:acme:mx/supplier:rfc=XYZ123456789

The left side combines tenant and legal entity by country. The right side respects the local convention without the gateway knowing anything about it. Adding a new subsidiary or tenant means registering an additional resolver, without touching existing references. The context hierarchy grows naturally with the system.

How the gateway works

The resolution flow is simple: the gateway receives the identifier, extracts the context, and delegates to the corresponding resolver.

client  →  gateway  →  resolver(commerce:orders)  →  actual service

Receives the identifier
Extracts the context (left side)
Delegates to the registered resolver for that context
The resolver fetches the resource and returns the response

The gateway has no knowledge of concrete resources. As an orientative reference, a possible Java implementation:

gateway.register("commerce:orders",   new OrderResolver());
gateway.register("finance:accounts",  new AccountResolver());
gateway.register("health:coverage",   new CoverageResolver());

public interface ResourceResolver {
    Response resolve(ResourceIdentifier identifier);
}

Optional preferences

The identifier supports expressing preferences about how the resource should be resolved, with a syntax inspired by HTTP's Accept header. For example, when querying available payment methods, you can indicate a preference for debit over credit:

payments:methods/available:customer:id=109234;debit,q=0.9;credit,q=0.7

The meaning of q is defined by the contract between whoever builds the reference and whoever resolves it. The gateway doesn't need to interpret it. This capability is completely optional.

I implemented this in Java and found it useful in practice. If you try it in your own context or have ideas to improve it, I'd love to read them in the comments.

[ES] Delegated Resource Identifier (DRI): un patrón para referencias persistentes en microservicios

Edgardo Genini — Wed, 13 May 2026 01:36:45 +0000

También disponible en Inglés

Si alguna vez guardaste una URL en una base de datos y después te arrepentiste, esto es para vos.

Es un escenario conocido: un servicio necesita mantener una referencia a un recurso que vive en otro servicio. La solución más obvia es guardar la URL. Funciona, hasta que el host cambia, la API sube de versión, o el equipo decide reestructurar los paths. De repente todas las referencias guardadas están rotas, y rastrear el impacto se convierte en un problema mayor de lo que debería ser.

El problema de fondo es que una URL mezcla dos cosas distintas: qué es el recurso y dónde está. Cuando guardás una URL estás apostando a que esa ubicación no va a cambiar. En sistemas que evolucionan, esa apuesta suele perderse.

La idea

¿Qué pasaría si en lugar de guardar dónde está el recurso, guardás un identificador propio que un gateway sabe cómo resolver?

comercio:pedidos/orden:id=ARG-2024-00091872
finanzas:cuentas/cliente:estado:id=109234
salud:cobertura/credencial:patient-id=12345678

Quien guarda la referencia no necesita saber dónde vive el recurso ni cómo se accede. Esa responsabilidad la tiene el gateway. Si la API cambia, si el servicio migra, si aparece un sistema nuevo: solo cambia el resolver. Las referencias guardadas siguen siendo válidas.

A este esquema lo llamé Delegated Resource Identifier (DRI).

Lo que este patrón no es

No es un estándar
Requiere un gateway como intermediario: no aplica cuando el cliente necesita acceder directamente al recurso sin pasar por ningún intermediario
No impone una taxonomía de contextos: cada equipo define la suya

Es una convención útil cuando necesitás referencias persistentes a recursos en un ecosistema controlado, y querés centralizar la lógica de resolución.

Cómo se construye

El identificador tiene dos partes separadas por /:

<contexto>/<recurso>

Contexto (lado izquierdo): identifica el dominio que sabe resolver este tipo de recurso. El gateway lo usa para rutear.
Recurso (lado derecho): identifica el recurso concreto. Su estructura la define quien implementa el resolver.

comercio:pedidos/orden:id=ARG-2024-00091872
└─── ruteo ──────┘└─── recurso concreto ──┘

Los : separan niveles jerárquicos. El = asigna valores. Cada lado define su propia convención interna.

El identificador lo construye quien guarda la referencia, a partir del dato que ya tiene y el contexto que conoce. No requiere ninguna llamada externa. Un servicio de facturación que recibe el ID de una orden sabe que pertenece a comercio:pedidos y construye el DRI al momento de persistir la referencia.

El contexto puede omitirse si el gateway tiene un resolver por defecto:

/orden:id=ARG-2024-00091872

Algunos casos de uso

E-commerce: recuperar una orden

Un servicio de atención al cliente guarda referencias a órdenes que pueden venir de distintos canales: tienda propia, marketplace, app móvil. Cada canal tiene su propia API.

comercio:pedidos/orden:id=ARG-2024-00091872
comercio:pedidos/orden:id=MKT-2024-00034521

El resolver de comercio:pedidos determina a qué canal pertenece cada orden a partir del prefijo del ID y rutea hacia la API correspondiente. El identificador es estable aunque la API del canal cambie.

Fintech: estado de cuenta de un cliente

Un banco con sistemas legacy y modernos conviviendo. El resolver determina en qué sistema vive el cliente según el valor del ID: clientes con id < 50000 en el sistema legacy, el resto en el moderno.

finanzas:cuentas/cliente:estado:id=109234
finanzas:cuentas/cliente:estado:id=002871

El resolver encapsula también la decisión de qué versión de la API usar. Y acá aparece algo interesante: el DRI tiene dos momentos de vida. Cuando se persiste es solo el identificador. Cuando se usa para consultar, puede enriquecerse con contexto adicional usando la misma sintaxis:

finanzas:cuentas/cliente:estado:id=109234:fecha=20260101

El resolver puede usar esa fecha para determinar qué versión de la API corresponde. El DRI persistido no cambia; el contexto adicional se agrega en el momento de la consulta.

Salud: credencial de cobertura de un afiliado

La cobertura de un afiliado puede cambiar en el tiempo: migración de proveedor, períodos sin cobertura, cobertura en más de uno. Guardar el proveedor como dato fijo generaría referencias desactualizadas.

salud:cobertura/credencial:patient-id=12345678

El resolver aplica una estrategia de fallback: consulta al primer proveedor disponible y si no encuentra la credencial prueba con el siguiente. El DRI resuelve en el momento de la consulta, reflejando siempre el estado actual.

Multinacional con tenant: proveedor por entidad legal

Una plataforma SaaS con operaciones en múltiples países. Cada país tiene su propio sistema, su propia API y su propio formato de identificador fiscal.

tenant:acme:ar/proveedor:cuit=20123456789
tenant:acme:cl/proveedor:rut=76354921-5
tenant:acme:mx/proveedor:rfc=XYZ123456789

El lado izquierdo combina tenant y entidad legal por país. El lado derecho respeta la convención local. Agregar una nueva filial o un nuevo tenant es registrar un resolver adicional, sin tocar las referencias existentes. La jerarquía del contexto crece naturalmente con el sistema.

Cómo funciona el gateway

El flujo de resolución es simple: el gateway recibe el identificador, extrae el contexto y delega al resolver correspondiente.

cliente  →  gateway  →  resolver(comercio:pedidos)  →  servicio real

Recibe el identificador
Extrae el contexto (lado izquierdo)
Delega al resolver registrado para ese contexto
El resolver obtiene el recurso y devuelve la respuesta

El gateway no conoce recursos concretos. A modo de referencia orientativa, una posible implementación en Java:

gateway.register("comercio:pedidos", new OrderResolver());
gateway.register("finanzas:cuentas", new AccountResolver());
gateway.register("salud:cobertura",  new CoverageResolver());

public interface ResourceResolver {
    Response resolve(ResourceIdentifier identifier);
}

Preferencias opcionales

El identificador admite expresar preferencias sobre cómo debe resolverse el recurso, con una sintaxis inspirada en el header Accept de HTTP. Por ejemplo, al consultar medios de pago se puede indicar preferencia por débito sobre crédito:

pagos:medios/disponibles:cliente:id=109234;debito,q=0.9;credito,q=0.7

El significado de q lo define el contrato entre quien construye la referencia y quien la resuelve. El gateway no necesita interpretarlo. Esta capacidad es completamente opcional.

Lo implementé en Java y me resultó útil en la práctica. Si lo probás en tu contexto o tenés ideas para mejorarlo, me interesa leerlo en los comentarios.