Diseñar la API de una biblioteca desde el dominio

Si el problema es hacer visible y accesible el mundo que la biblioteca modela, entonces el nombre de cada tipo y función debe nombrar un concepto real del dominio, no un detalle de implementación.

Un modelo de dominio es la representación de los conceptos, reglas y relaciones que una biblioteca necesita expresar para resolver un problema.

La API debería exponer como tipos explícitos aquellos conceptos del dominio que tienen identidad, reglas o restricciones propias. Para que eso funcione, los nombres deben ser suficientemente claros dentro del contexto de la biblioteca: un tipo como Address comunica mejor que uno ambiguo como Direction si lo que se modela es una dirección postal. Cuando el contexto no basta, conviene preferir nombres más específicos que ayuden a entender la intención sin depender por completo de documentación externa.

No todo concepto del dominio merece su propio tipo público. Introduce tipos cuando el concepto cumple al menos una de estas características:

• Tiene reglas o restricciones: p. ej., un código postal válido, un monto no negativo, un correo con formato específico.
• Tiene identidad o significado propio: p. ej., AccountAccount no es solo un número; es un concepto con historial, propietario, estado.
• Necesita métodos especializados: p. ej., AddressAddress podría tener normalize()normalize() o distance_to(other)distance_to(other).

Si un concepto es solo un agregado transitorio de datos sin reglas, un tipo primitivo o una tupla/record anónima puede bastar.

Si el problema es garantizar que ciertos invariantes nunca puedan romperse y que la biblioteca pueda evolucionar sin sorpresas, entonces la implementación debe quedarse privada y las reglas críticas deben ser imposibles de romper desde afuera.

Una API encapsulada expone solo la información que quien consume necesita conocer y mantiene privados los detalles internos: cómo se almacenan los datos, qué algoritmos se usan, qué estructuras de caché o índices hay. Si el dominio tiene reglas invariantes (p. ej., una orden siempre debe tener al menos un articulo), la encapsulación garantiza que esas reglas no puedan romperse desde afuera.

• Ocultar detalles: no expongas estructuras internas como si fueran parte de la interfaz pública. Usa visibilidades privadas y módulos para separar lo interno de lo público.
• Proteger invariantes: si la regla del dominio dice "un saldo nunca puede ser negativo", haz imposible desde fuera romper esa regla. Usa constructores privados y métodos verificadores.
• Libertad de evolucionar: si quieres cambiar la estructura interna de una clase sin afectar consumidores, primero debes haber ocultado esa estructura tras métodos públicos.

Si el problema es que quien usa acceda fácilmente a lo que necesita sin abrumarle con opciones innecesarias, entonces cada elemento público debe justificar claramente su existencia.

Minimalidad útil no significa ofrecer menos de lo necesario, sino evitar variantes, extensiones y conveniencias que no aportan claramente al problema que la biblioteca resuelve. Una API pequeña se aprende más rápido, se usa con menos ambigüedad y también suele ser más fácil de mantener y evolucionar.

• No expongas alternativas equivalentes: si una operación ya está bien representada por get_balance()get_balance(), evita sumar variantes como fetch_balance()fetch_balance(), consult_balance()consult_balance() o balance_getter()balance_getter() sin una diferencia real de comportamiento.
• No incluyas funcionalidades «por si acaso» : no agregues opciones que nadie necesita todavía. Cada elemento público nuevo amplía la API y hace más difícil su evolución futura.
• Evita operaciones demasiado específicas: si un caso particular puede resolverse combinando bien la API principal, probablemente no necesita una función pública propia.
• Pero sí, sé completo: si una capacidad forma parte del problema central que la biblioteca promete resolver, no la omitas. La minimalidad útil elimina lo accesorio, no lo esencial.

Si el problema es que quien consume entienda rápidamente qué hace cada operación, entonces los nombres deben ser consistentes, los tipos deben evitar errores silenciosos y los errores deben ser informativos.

• Consistencia: mantén patrones estables en nombres y política de retorno.
• Descubribilidad: los nombres deben sugerir qué hacen. Prefiere verbos claros y específicos del dominio (transferFunds, registerAccount) antes que genéricos (exec, process). Si el IDE muestra autocompletado, debería ser fácil orientarse.
• Difícil de usar mal: usa tipos para que el compilador rechace código incorrecto. Crea tipos específicos (Email, Amount) en lugar de primitivos genéricos. Así quien consume no puede pasar datos inválidos ni en orden equivocado.

Todos los principios anteriores dicen: piensa en quien usa la API. Es el criterio más importante porque guía todas las decisiones. Modelar bien el dominio, proteger invariantes, limitar opciones y comunicar claramente solo tienen sentido si están pensados desde el punto de vista de quien le dará uso.

Una API bien diseñada muestra empatía con quien la consume. Eso no significa complacer cualquier petición, sino entender necesidades reales, errores probables y el contexto en que otras personas usarán tu código.

Por ejemplo, si tu biblioteca maneja dinero, conviene anticipar confusiones entre unidades, errores frecuentes al construir montos o dudas sobre cómo manejar fallos. Los tipos, los nombres y los ejemplos deberían ayudar a evitar esas fricciones.

• Haz fácil lo común, sin sacrificar lo importante: la operación más frecuente debería ser reconocible y requerir pocos pasos, pero los casos especiales deben tener respuestas claras.
• Errores que comunican claridad: si algo falla, el error debe explicar por qué sucedió y sugerir cómo reaccionar. No expongas detalles internos confusos ni códigos enigmáticos.
• Valida tu diseño con casos reales: antes de publicar, usa tu propia API. Implementa un caso de uso completo. ¿Fue intuitivo? ¿Fácil de extender? Si no, todavía hay deuda de diseño.