De dónde viene API#

API abrevia Application Programming Interface. El término es anterior a la Web y su idea central es aún más antigua: permitir que un programa use una capacidad sin depender de cómo está construida.

La API, por tanto, no nació como sinónimo de endpoint HTTP ni de servicio público. Esos son mecanismos posteriores para expresar una interfaz. También son APIs las funciones de una biblioteca, las llamadas de un sistema operativo o cualquier protocolo que permita colaborar con una capacidad encapsulada.

Cómo lo reinterpreta API-DD#

API-DD conserva esa función histórica de la interfaz: separar al consumidor del mecanismo. La amplía con una idea de Alan Kay: en un sistema capaz de crecer importa más diseñar cómo se comunican sus módulos que fijar sus propiedades internas. Kay situó el intercambio de mensajes en el núcleo de Smalltalk, pero su observación sobre módulos y comunicación puede aplicarse fuera de la orientación a objetos (mensaje original de 1998).

API-DD lleva la API desde el límite exterior de una aplicación hasta cada relación modular que merezca un contrato. La conversación puede ser local o remota y expresarse con funciones, métodos, eventos o HTTP. El mecanismo cambia; la separación entre consumidor e implementación permanece.

Esta es una reinterpretación deliberada, no la afirmación de que API haya significado siempre exactamente lo mismo. De su historia tomamos la separación entre uso e implementación; de Kay, el foco en los mensajes entre módulos. De ahí surge API-Driven Development.

Manifiesto#

El software cambia. Sus contratos permiten que cambie sin obligar a cada consumidor a conocer de nuevo su interior.

1. Las interacciones importan más que la forma interna. Un módulo se entiende por las conversaciones que ofrece y consume.
2. El vocabulario forma parte del diseño. Los nombres expresan intenciones, resultados y hechos que otros módulos pueden comprender.
3. Lo visible crea acoplamiento. La API muestra lo necesario y mantiene reemplazables algoritmos, coordinación y representación.
4. La autonomía llega hasta cada resultado. Un módulo completo y válido cumple su contrato sin pedir al consumidor que repare su estado, y entrega resultados que no comparten referencias mutables.
5. El contrato puede verificarse desde fuera. Los tests actúan como consumidores y observan resultados, estado o mensajes públicos.

Estos fundamentos pueden aplicarse de forma recursiva cuando un módulo se descompone en otros módulos con contratos propios. API-DD no prescribe una arquitectura, un paradigma ni un orden de trabajo. Ofrece una perspectiva para diseñar las conversaciones que mantienen unido el sistema.

Definición#

API-Driven Development (API-DD) propone diseñar cada módulo como una API: hacer visibles los mensajes que acepta, las garantías que conserva, los detalles que oculta y las APIs que necesita.

El punto de partida no es la clase, la carpeta ni el patrón que vamos a utilizar. Es el contrato mediante el que un módulo colabora con los demás. Antes de resolver su interior, aclaramos qué API ofrece y qué compromisos deben sobrevivir a cualquier implementación correcta. Es una perspectiva de diseño, no una arquitectura ni un conjunto de reglas obligatorias.

En este libro, módulo no significa necesariamente un módulo del lenguaje, un paquete, un servicio desplegable ni un archivo. Es una parte encapsulada del software que otros utilizan mediante un contrato. Según la escala, puede materializarse como un conjunto de funciones, un tipo, un paquete, un proceso o una combinación de ellos.

Una API puede expresarse con funciones, métodos, eventos, endpoints o cualquier otro mecanismo. Lo importante es la conversación, no su sintaxis.

Diseñar la API#

Diseñar la API exige identificar al consumidor, los mensajes que necesita, lo que puede observar y las garantías que deben conservarse. También separa los detalles ocultos y las APIs que el módulo necesita. Esas decisiones forman el contrato; la firma es solo su representación más visible.

Un ejemplo pequeño#

Supongamos un módulo que aplica un estilo a un texto:

Formatter.Format(Text, Style) → FormattedText | UnsupportedStyle

Formatter es el módulo y Format es un mensaje de su API. Text, Style, FormattedText y UnsupportedStyle forman el vocabulario del contrato. Conviene precisar qué significan y qué puede hacer el consumidor con ellos, pero no son APIs independientes por el mero hecho de aparecer en la firma.

El contrato promete que un estilo admitido produce texto formateado, uno desconocido devuelve un error distinguible y el original no cambia. La librería utilizada permanece oculta.

El consumidor no necesita conocer si el proveedor usa una plantilla, un árbol intermedio o una librería externa. Esas decisiones pueden cambiar mientras se conserven las garantías.

Ejemplo en Go#

Go puede expresar la conversación mediante una interfaz y un error distinguible.

import "errors"

type Text string
type Style string
type FormattedText string

var ErrUnsupportedStyle = errors.New("unsupported style")

type Formatter interface {
    Format(Text, Style) (FormattedText, error)
}

La representación podría cambiar mientras Formatter, Format y el significado de ErrUnsupportedStyle conserven el contrato.

Una forma de aplicarlo#

Una aplicación mínima de API-DD tiene tres pasos:

1. Identifica al consumidor y la conversación que necesita.
2. Fija mensajes y garantías observables, dejando fuera el mecanismo.
3. Implementa y prueba el contrato; repite el análisis solo si aparece otra relación con contrato propio.

API-DD no sustituye el modelado del dominio, la arquitectura ni TDD. Ayuda a concretar cómo colaboran los módulos que esas disciplinas descubren.

API-DD permite mirar cada módulo como una API y conservar libre su implementación.

Una API puede conceptualizarse como un módulo#

Para diseñar una API resulta útil conceptualizarla como un módulo visto desde fuera. El módulo reúne una capacidad y conserva su implementación; la API es el límite por el que otros colaboran con él.

No son exactamente lo mismo. Un módulo puede ofrecer más de una conversación a consumidores diferentes y también consumir otras APIs. La equivalencia sirve como herramienta de diseño: cuando aparece una API relevante, buscamos el módulo responsable de sostener su contrato.

módulo
├── API ofrecida → consumidores
├── implementación oculta
└── APIs consumidas → otros módulos

El módulo puede materializarse como una función, un tipo, un paquete, un proceso o varios elementos coordinados. Su forma técnica no determina su escala conceptual.

El interés está en las interacciones#

API-DD pone el interés en lo que ocurre entre módulos: mensajes, respuestas, errores, efectos y garantías. Esta mirada sigue la idea de Alan Kay presentada en la introducción: los sistemas crecen mejor cuando se diseña cómo se comunican sus módulos, no cuando se fija de antemano todo su interior.

Mirar las interacciones aclara qué necesita el consumidor, qué módulo responde, qué puede observarse y qué decisiones internas pueden cambiar. También muestra las APIs que ese módulo consume.

El algoritmo sigue siendo importante, pero pertenece a otro nivel. Primero se distingue qué debe sobrevivir a cualquier implementación correcta y después se elige cómo conseguirlo.

Todos los fundamentos se repiten#

Cuando un módulo se descompone en módulos con contratos propios, los cinco fundamentos pueden aplicarse de nuevo en cada límite:

La recursión no convierte cada parámetro, helper o estructura en otra API. Value, Result o Error forman parte del vocabulario de un mensaje. Solo pasan a considerarse módulos cuando reúnen comportamiento, tienen consumidores o necesitan evolucionar mediante un contrato propio.

Dónde continuar y dónde detenerse#

La perspectiva se repite cuando una capacidad tiene otro consumidor, garantías propias o evolución independiente, o cuando la interacción cruza un límite técnico u organizativo relevante.

Se detiene cuando la decisión solo explica cómo trabaja el módulo actual. Un bucle, un índice o una función auxiliar no necesitan una API propia si ninguna relación externa depende de ellos.

Esto evita confundir recursión con una jerarquía infinita de interfaces. El objetivo es reconocer límites útiles, no fabricar capas.

Ejemplo en Go#

Un Pipeline ofrece una API y consume la API de cada Stage. El recorrido del arreglo permanece dentro de su implementación.

type Stage interface {
    Apply([]byte) ([]byte, error)
}

type Pipeline struct {
    stages []Stage
}

func (p Pipeline) Run(value []byte) ([]byte, error) {
    var err error
    for _, stage := range p.stages {
        value, err = stage.Apply(value)
        if err != nil {
            return nil, err
        }
    }
    return value, nil
}

Pueden existir muchas implementaciones de Stage. Cada una puede revisarse otra vez como módulo, mientras que el recorrido del slice sigue siendo un detalle de Pipeline.

Revisión práctica#

Nombra la API, el módulo responsable, sus consumidores y las APIs que necesita. Solo profundiza en colaboraciones con contrato propio; algoritmos y helpers permanecen dentro del módulo. La descomposición es útil si aclara una relación real.

La recursión sigue las conversaciones entre módulos, no cada línea de código.

Diseñar el vocabulario#

Un nombre no decora una solución terminada. Decide qué concepto verá el consumidor y qué podrá esperar de él.

Cuando una API usa palabras como execute, data o response, obliga a leer la implementación para descubrir su significado. Cuando nombra una intención, un resultado o una situación reconocible, permite entender el contrato sin abrir la implementación.

El vocabulario de una API debería seguir siendo verdadero aunque cambie su implementación.

Todo valor que cruza una API necesita significado, reglas de validez e igualdad, una representación de la ausencia y un propietario para su estado mutable. El consumidor solo debería observar la representación que el contrato decida conservar.

La respuesta no siempre requiere un tipo nuevo. Un tipo propio aporta cuando nombra una diferencia, protege una invariante o impide una combinación inválida. Si el contexto ya evita la confusión y las reglas son las mismas, separar dos valores solo añade ceremonia.

Ejemplo: añadir una tarea a una cola#

Esta firma describe principalmente la organización del código:

QueueService.Execute(EnqueueCommand) → QueueResponse

No sabemos qué se ejecuta, qué contiene la respuesta ni qué puede salir mal. La misma capacidad puede expresarse así:

Queue.Enqueue(Task) → Position | QueueFull

Queue aporta el contexto, Enqueue expresa la intención, Task nombra la entrada, Position el resultado y QueueFull una situación ante la que el consumidor puede actuar.

La implementación puede usar memoria, archivos o un sistema remoto. Ninguna de esas decisiones obliga a cambiar el mensaje.

Ejemplo en Go#

El ejemplo mantiene Queue, Enqueue, Task, Position y QueueFull como vocabulario visible.

import "errors"

type Task struct{ ID string }
type Position int

var ErrQueueFull = errors.New("queue full")

type Queue interface {
    Enqueue(Task) (Position, error)
}

Nombres exportados#

Los nombres públicos son el vocabulario compartido entre un módulo y sus consumidores. Merecen más estabilidad que los identificadores internos porque aparecen en llamadas, documentación, tests y, a veces, datos serializados.

Cada lenguaje expresa esa frontera de otra forma. En Go, un identificador exportado comienza con mayúscula; los nombres con minúscula permanecen dentro del paquete. Un directorio internal también permite limitar qué parte del árbol puede importar un paquete.

Exportar no mejora un nombre ni convierte un tipo en una buena abstracción. Primero se identifica qué necesita nombrar el consumidor; después se le da la visibilidad correspondiente. Los helpers y representaciones internas pueden usar palabras más técnicas sin contaminar la conversación pública.

Buenos nombres#

El módulo#

El nombre de un módulo debe indicar la capacidad que reúne, no el patrón con el que fue construido.

Manager, Service, Handler, Facade o Helper suelen ser débiles cuando aparecen solos. Clasifican una estructura técnica, pero no explican qué ofrece. QueueManager, por ejemplo, permite imaginar casi cualquier responsabilidad; Queue establece un contexto concreto para mensajes como Enqueue, Next o Remove.

Esto no convierte los nombres técnicos en un error universal. En la composición puede ser útil distinguir MemoryQueue de RemoteQueue, porque allí el consumidor elige una implementación. La API que ambas proporcionan puede seguir llamándose Queue.

La pregunta útil es: ¿el consumidor necesita conocer este mecanismo? Si la respuesta es no, el nombre técnico pertenece al interior.

Los mensajes#

Los mensajes expresan intenciones o hechos, no pasos internos.

Un verbo como Enqueue permite anticipar el efecto. Run, Execute, Process o Handle solo son precisos cuando ejecutar, procesar o despachar constituye realmente la capacidad del módulo.

La prueba más sencilla consiste en leer el uso como una frase:

position = queue.Enqueue(task)

Si para entenderla hay que traducir categorías del framework, el contrato todavía habla desde la implementación.

Valores y resultados#

Un tipo merece nombre cuando representa una diferencia que importa. Task, Position y Capacity dicen más que Data, Item o ValueObject, siempre que esas sean las palabras del contexto real.

Los sufijos que repiten la categoría técnica suelen sobrar:

TaskModel
PositionValueObject
QueueResponseDTO

Pueden ser necesarios dentro de un adaptador que traduce dos representaciones, pero no deberían propagarse a la API principal por accidente.

Las unidades también forman parte del significado. Delay puede resultar ambiguo si el consumidor necesita distinguir milisegundos de segundos. No siempre hace falta un nombre más largo; sí hace falta conservar la diferencia que evita un uso incorrecto.

Booleanos, errores y eventos#

Un booleano se entiende mejor como una proposición:

queue.IsFull()
queue.Contains(taskID)

Check, Flag o Status no aclaran qué significa true. Si existen más de dos resultados relevantes, probablemente el contrato necesite un estado nombrado en lugar de un booleano.

Los errores públicos describen situaciones ante las que el consumidor puede reaccionar. QueueFull permite esperar o elegir otra cola. DatabaseError filtra infraestructura y quizá no ofrece ninguna decisión útil. Los detalles técnicos pueden conservarse como causa interna, log o diagnóstico sin convertirse en vocabulario estable.

Un evento nombra un hecho que ya ocurrió. TaskQueued evita confundir la notificación con la petición EnqueueTask. El pasado también ayuda a que el nombre siga siendo cierto aunque cambie el transporte.

Comunicación#

El vocabulario funciona como un sistema, no como una lista de términos aislados. Módulo, mensaje, argumentos y resultados deben poder leerse juntos como una conversación.

El contexto evita repeticiones#

La precisión no consiste en incluir toda la explicación en cada identificador:

queue.Enqueue(task)

es más claro que:

queueService.ExecuteTaskEnqueueCommand(taskValueObject)

En el primer caso, módulo, mensaje y argumento reparten el significado. En el segundo, las categorías técnicas añaden longitud sin explicar mejor el contrato.

Un nombre corto puede ser ambiguo y uno largo puede compensar un contexto mal elegido. La meta es usar las palabras mínimas que conserven el significado donde se leen.

Encontrar un nombre#

Para encontrar el nombre, describe primero la intención del consumidor: «quiero añadir esta tarea a la cola». Separa contexto, acción, valores y resultados; usa las palabras del problema y lee la llamada completa. Después imagina otra implementación: si el nombre deja de ser cierto, todavía describe el mecanismo.

Si cuesta nombrar un módulo, puede haber responsabilidades mezcladas o una abstracción prematura. En ese caso conviene volver a la conversación antes de buscar un sinónimo más elegante.

Esta práctica coincide con el lenguaje ubicuo de DDD: los nombres ganan precisión dentro de un contexto explícito, no en un diccionario universal (DDD Reference, Eric Evans). API-DD añade una comprobación concreta: el vocabulario debe funcionar desde el módulo consumidor y sobrevivir a implementaciones alternativas.

Renombrar es migrar#

Una vez publicada, una palabra forma parte del contrato. Cambiarla puede romper compilación, mensajes serializados, documentación, métricas o integraciones.

Una migración puede requerir introducir el nombre nuevo junto al anterior, adaptar consumidores y retirar el alias cuando ya no exista dependencia. Que el nombre nuevo sea mejor no vuelve inocuo el cambio.

Un buen nombre explica la conversación y no delata el mecanismo que la hace posible.

Visibilidad y acoplamiento#

Una API es el protocolo que permite a dos módulos colaborar. Su contrato reúne la información mínima que un consumidor necesita para usarla sin conocer su implementación.

Una firma puede mostrar nombres y tipos:

Set.Add(Value) → AddResult

Pero no explica por sí sola si se permiten duplicados, cómo se compara un valor, qué cambia después de la llamada ni qué ocurrirá al repetirla. Esas garantías también pertenecen al contrato.

Cada elemento visible crea una dependencia: el consumidor puede utilizarlo y el proveedor tendrá que conservarlo o migrarlo. Reducir visibilidad disminuye acoplamiento solo cuando la API sigue expresando toda la capacidad necesaria.

Lo que puede observar el consumidor#

No todas las APIs necesitan documentar cada dimensión con el mismo detalle. La profundidad depende del riesgo y del número de consumidores. Un módulo local con una operación pura puede quedar claro con una firma y dos ejemplos; un protocolo compartido necesitará más precisión.

Ejemplo: un conjunto sin duplicados#

Consideremos esta API independiente:

Set.Add(Value)      → Added | AlreadyPresent
Set.Contains(Value) → bool
Set.Size()          → integer

Su contrato establece que añadir un valor ausente devuelve Added y hace que Contains sea verdadero. Repetirlo devuelve AlreadyPresent sin aumentar Size.

El contrato aún necesita una decisión sobre igualdad: ¿cuándo representan dos valores lo mismo? No necesita decidir si la implementación usa una tabla hash, un árbol o una lista. Cualquiera de ellas es válida si conserva las garantías.

Este ejemplo también muestra la diferencia entre API y vocabulario. Value, Added y AlreadyPresent forman parte de los mensajes. No son tres APIs nuevas. Solo necesitarían contratos independientes si adquirieran comportamiento, consumidores o evolución propios.

Ejemplo en Go#

Esta implementación protege el contrato y deja la estructura interna fuera de la API.

type AddResult uint8

const (
    Added AddResult = iota
    AlreadyPresent
)

type UniqueSet[T comparable] struct {
    values map[T]struct{}
}

func (s *UniqueSet[T]) Add(value T) AddResult {
    if s.values == nil {
        s.values = make(map[T]struct{})
    }
    if _, exists := s.values[value]; exists {
        return AlreadyPresent
    }
    s.values[value] = struct{}{}
    return Added
}

func (s *UniqueSet[T]) Contains(value T) bool {
    _, exists := s.values[value]
    return exists
}

func (s *UniqueSet[T]) Size() int {
    return len(s.values)
}

API pública e implementación#

Una decisión pertenece a la API cuando un consumidor legítimo necesita utilizarla o distinguirla y el proveedor está dispuesto a conservarla.

Una superficie pequeña es útil si permite expresar la capacidad completa. Ocultar una diferencia necesaria no reduce acoplamiento: obliga al consumidor a deducirla o a buscarla en la implementación.

Estado y efectos#

El resultado inmediato es solo una forma de observación. Un mensaje puede modificar estado que luego se consulta mediante la API o producir un efecto dirigido a otro módulo.

El contrato debe nombrar esos efectos cuando el consumidor depende de ellos. No debe publicar la coordinación utilizada para conseguirlos.

En el ejemplo del conjunto, Size y Contains permiten observar el estado sin exponer su representación. El consumidor puede comprobar la garantía sin recibir la colección interna ni modificarla por referencia.

Cuando la API devuelve colecciones o estructuras mutables, hay que decidir quién conserva su propiedad. Si siguen perteneciendo al proveedor, una copia o una vista inmutable puede evitar cambios accidentales. Si la propiedad se transfiere, conviene decirlo de forma explícita.

Repetición e idempotencia#

Una operación es idempotente cuando repetir la misma intención produce el mismo efecto observable que ejecutarla una vez. No significa que el proveedor ejecute una sola instrucción ni que devuelva la misma instancia.

Set.Add es idempotente respecto del contenido: repetir el mismo valor no crea otra entrada. La respuesta puede cambiar de Added a AlreadyPresent y la garantía seguir siendo válida, porque el estado final no cambia.

La idempotencia solo merece entrar en el contrato cuando existen reintentos, repeticiones o entregas duplicadas que el consumidor deba poder manejar. Añadirla sin necesidad introduce identidad, estado y costes de retención.

Compatibilidad#

Una API publicada acumula consumidores. Cambiar un nombre, una regla de validez, un error o el significado de un campo puede romperlos aunque el código siga compilando.

Antes de modificar el contrato hay que conocer sus consumidores y el comportamiento que observan. Si el cambio no puede ser aditivo, se necesita una convivencia temporal y una condición explícita para retirar la versión anterior.

La compatibilidad no exige conservar para siempre una mala decisión. Exige tratar su corrección como una migración y no como un refactor interno.

Revisión práctica#

Antes de implementar una API, comprueba tres cosas:

1. El consumidor puede expresar su intención y distinguir los resultados relevantes.
2. Estado, efectos y propiedad de los valores están claros.
3. El mecanismo sigue siendo reemplazable y la compatibilidad se trata solo donde importa.

Un buen contrato permite dos cosas a la vez: que el consumidor use el módulo con confianza y que el proveedor cambie su interior con libertad.

Autonomía en cada escala#

La autonomía no aparece únicamente en el módulo más grande. Puede fomentarse de forma granular cada vez que la perspectiva de API-DD se aplica recursivamente.

Autonomía no significa aislamiento. Un módulo puede consumir otras APIs y un resultado puede contener varios valores. La diferencia es que cada elemento conserva un límite claro: ningún consumidor necesita reparar su estado, completar su significado ni conocer una representación ajena.

Aplicar el fundamento a un resultado no lo convierte en otro módulo. El resultado sigue siendo vocabulario de la API, pero también necesita propiedad y validez propias.

API autónoma#

Una API es autónoma cuando el consumidor puede expresar una intención y comprender la respuesta dentro de la misma conversación. No necesita abrir la implementación, consultar una estructura interna ni coordinar colaboradores que pertenecen al proveedor.

Una secuencia pública puede formar parte de un protocolo real. Pierde autonomía cuando sus pasos solo existen para terminar de montar el módulo:

value := Interval{}
value.SetStart(2)
value.SetEnd(8)
value.Validate()

La intención completa puede expresarse en un solo mensaje:

Interval.New(2, 8) → Interval | InvalidInterval

La autonomía tampoco exige que cada respuesta incluya todos los datos imaginables. Incluye lo necesario para que el consumidor actúe ante las diferencias que el contrato reconoce.

Módulo completo#

Un módulo es completo cuando reúne lo necesario para cumplir el contrato que ofrece. El consumidor usa su capacidad mediante la API sin completar pasos internos, corregir su estado ni decidir cómo deben coordinarse sus dependencias.

Completo no significa autosuficiente. El módulo puede leer, calcular o producir efectos mediante otras APIs. Su responsabilidad consiste en gobernar esas colaboraciones y traducirlas al contrato que ofrece.

Una señal de incompletitud aparece cuando varios consumidores repiten la misma coordinación para obtener una capacidad que debería pertenecer al módulo. La solución no es esconder cualquier secuencia: es asignar la responsabilidad al límite que puede garantizarla.

Módulo válido#

Un módulo válido conserva sus invariantes en todos los estados observables. Puede rechazar una entrada o devolver un error; evita continuar con un estado incoherente que otro consumidor tenga que descubrir después.

La validez se protege en cada entrada de información: construcción, cambios de estado, datos externos, persistencia y resultados de otras APIs.

Un estado inicial vacío puede ser válido. También puede ser inválido pero seguro. La API debe distinguirlo antes de producir un efecto incorrecto.

Resultados autónomos#

Un resultado autónomo pertenece a la conversación que lo recibe. Su significado está completo y su contenido no cambia porque el proveedor continúe trabajando ni porque otro consumidor lo utilice.

Esto requiere evitar referencias compartidas a estado mutable. Devolver directamente un slice, un mapa o un puntero interno permite que el consumidor modifique al proveedor y que el proveedor altere un resultado ya entregado. Ambos dejan de ser autónomos.

Puede conservarse la autonomía mediante valores copiados, campos privados y operaciones de lectura, o una transferencia explícita de propiedad. Si copiar resulta demasiado costoso, el módulo puede ofrecer una API de recorrido sin exponer su colección interna.

Go no tiene una declaración general de inmutabilidad. Aquí, inmutable significa que la API pública no permite cambiar el resultado y que el proveedor no puede alterarlo después de entregarlo. Un struct copiado puede contener slices, mapas o punteros que aún comparten memoria; la autonomía debe llegar hasta cada referencia mutable, no detenerse en el tipo exterior.

Ejemplo en Go#

Collection conserva su estado y entrega un Snapshot autónomo. El snapshot copia los datos y solo ofrece operaciones de lectura.

package collection

import "errors"

var (
    ErrInvalidLimit = errors.New("invalid limit")
    ErrInvalid      = errors.New("invalid collection")
    ErrFull         = errors.New("collection full")
)

type Snapshot struct {
    values []string
}

func newSnapshot(values []string) Snapshot {
    return Snapshot{values: clone(values)}
}

func (s Snapshot) Len() int {
    return len(s.values)
}

func (s Snapshot) At(index int) (string, bool) {
    if index < 0 || index >= len(s.values) {
        return "", false
    }
    return s.values[index], true
}

type Collection struct {
    limit  int
    values []string
}

func New(limit int) (*Collection, error) {
    if limit <= 0 {
        return nil, ErrInvalidLimit
    }
    return &Collection{limit: limit}, nil
}

func (c *Collection) Add(value string) error {
    if c == nil || c.limit <= 0 {
        return ErrInvalid
    }
    if len(c.values) == c.limit {
        return ErrFull
    }
    c.values = append(c.values, value)
    return nil
}

func (c *Collection) Snapshot() Snapshot {
    if c == nil {
        return Snapshot{}
    }
    return newSnapshot(c.values)
}

func clone(values []string) []string {
    return append([]string(nil), values...)
}

New produce un módulo válido o un error. Add responde de forma segura incluso ante el valor cero de Go. Snapshot no conserva el slice de Collection ni lo expone: Len y At permiten leerlo sin ofrecer una operación de mutación.

Valores iniciales y ausencia#

En Go, todo tipo concreto tiene un valor cero. Publicar New no lo elimina. El contrato puede tratarlo como útil, como ausencia o como inválido pero seguro. La especificación de Go define el mecanismo; la API define su significado.

Ausente y presente con valor cero tampoco son siempre equivalentes. Si la diferencia cambia el comportamiento, puede representarse mediante (T, bool), un puntero o un resultado nombrado. Los formatos de transporte se traducen en el adaptador para que el módulo reciba significado, no detalles de serialización.

Dependencias autónomas#

Una dependencia forma parte de la construcción cuando el módulo no puede cumplir su contrato sin ella. Recibirla mediante una API hace visible qué necesita, pero no traslada su coordinación al consumidor.

No hace falta introducir una interfaz para cada helper. Una dependencia merece contrato propio cuando tiene otros consumidores o proveedores, cruza un límite relevante o evoluciona de forma autónoma. En ese punto los mismos fundamentos pueden aplicarse de nuevo.

Revisión práctica#

La API debe expresar una intención completa, y el módulo debe gobernar sus dependencias e invariantes. La creación produce un valor válido o un fallo explícito. Cada resultado contiene lo necesario para actuar y deja clara la propiedad de cualquier slice, mapa, puntero o elemento mutable.

La autonomía se conserva desde el módulo hasta el resultado que cruza su API.

El test como consumidor#

Un test funcional representa a un consumidor del módulo. Entra por su API y comprueba resultados, estado o mensajes que pertenecen al contrato.

La caja negra no tiene que abarcar todo el sistema. Puede ser un módulo pequeño siempre que la prueba respete su límite y no convierta la coordinación interna en una promesa pública.

test → API → implementación
                  └── API consumida → colaborador

La pregunta principal es qué debe seguir siendo cierto para el consumidor. La elección entre implementación real, doble de prueba o integración viene después.

Qué puede observar una prueba#

Un contrato ofrece tres clases de observación:

Los helpers utilizados, el reparto entre objetos internos y el algoritmo elegido quedan fuera. También quedan fuera el número y el orden de llamadas cuando no cambian el resultado observable.

Una prueba funcional debería aceptar dos implementaciones que produzcan los mismos resultados, el mismo estado visible y los mismos mensajes contractuales.

Ejemplo: conservar un valor ante un fallo#

Consideremos un módulo de caché:

Cache.Refresh(Key) → Value | SourceUnavailable
Cache.Get(Key)     → Value | NotFound

Cache consume otra API:

Source.Load(Key) → Value | error

Queremos demostrar una sola garantía: si la fuente falla durante una actualización, el valor anterior continúa disponible.

El test ejecuta la implementación real de Cache y prepara un doble de Source que devuelve un fallo. Después observa únicamente la API:

dado un valor almacenado para una clave
cuando Refresh recibe SourceUnavailable
entonces devuelve SourceUnavailable
y Get conserva el valor anterior

La prueba no necesita saber si la caché escribe primero en una copia, usa un bloqueo o revierte una asignación. Tampoco necesita una fuente remota real, porque el riesgo observado es la reacción del módulo al fallo, no el protocolo de red.

Una prueba diferente debería comprobar el adaptador real si el riesgo estuviera en la serialización, la configuración o el transporte.

Ejemplo en Go#

Suponiendo la API anterior, el caso puede escribirse sin observar ninguna llamada interna.

import (
    "errors"
    "testing"
)

type sourceStub struct{ err error }

func (s sourceStub) Load(string) (string, error) {
    return "", s.err
}

func TestRefreshKeepsPreviousValue(t *testing.T) {
    cache := NewCache(sourceStub{err: ErrSourceUnavailable})
    cache.Put("key", "previous")

    _, err := cache.Refresh("key")
    if !errors.Is(err, ErrSourceUnavailable) {
        t.Fatalf("expected source error, got %v", err)
    }

    got, _ := cache.Get("key")
    if got != "previous" {
        t.Fatalf("expected previous value, got %q", got)
    }
}

El test controla una entrada indirecta mediante un stub y comprueba resultado y estado. No exige cuántos helpers debe ejecutar la caché.

Hablar con el vocabulario habitual#

Doble de prueba es el término general para cualquier sustitución usada durante una prueba. Dentro de esa familia conviene mantener los significados conocidos, en lugar de redefinir fake para abarcarlo todo.

La terminología procede de la taxonomía recogida por Gerard Meszaros y resumida por Martin Fowler en Test Double. Saber el nombre ayuda, pero la decisión importante sigue siendo qué comportamiento sustituye el doble y qué riesgo deja sin cubrir.

En el ejemplo anterior basta un stub de Source: prepara el fallo que el caso necesita. Un fake funcional sería útil si muchos tests necesitaran una fuente en memoria con reglas estables. Un mock solo tendría sentido si una interacción concreta formara parte del contrato.

Elegir colaboradores#

La implementación real ofrece la mayor fidelidad y es la primera opción cuando resulta rápida, determinista, hermética, segura y fácil de construir. La guía de Software Engineering at Google sobre test doubles propone el mismo punto de partida pragmático.

No es necesario sustituir valores, entidades o funciones puras solo porque colaboren en el caso. Tampoco hace falta levantar infraestructura real para demostrar una regla que no depende de ella.

Cuándo observar interacciones#

Un mensaje saliente puede formar parte del contrato. En ese caso un spy o un mock permite observar su contenido, cantidad u orden.

La expectativa se limita al contenido, la cantidad o el orden solo cuando esa diferencia cambia el efecto para otro consumidor.

Comprobar que se llamó a un mapper, una query concreta o un helper privado congela la implementación. Comprobar que se publicó un mensaje requerido protege el contrato.

Una interacción solo demuestra que el mensaje se intentó enviar. No demuestra que el receptor real lo acepte. Cuando esa compatibilidad es el riesgo, hace falta una prueba del adaptador o una integración.

Qué debe conservar un fake#

Un fake funcional implementa un subconjunto declarado del contrato. Para los casos soportados acepta las mismas entradas y conserva resultados, errores y estado. Debe ser determinista, aislar cada test y hacer visibles las capacidades o propiedades que omite.

No necesita copiar la infraestructura. Una fuente en memoria puede reproducir lectura, ausencia y versiones sin simular red o latencia. Si el caso trata precisamente de esas propiedades omitidas, el fake deja de ser una prueba suficiente.

Un fake compartido acumula responsabilidad y merece tests propios. Cuando sea viable, una misma suite de contrato puede ejecutarse contra el fake y el adaptador real para detectar divergencias.

Método de revisión#

Para diseñar una prueba:

1. Nombra la garantía y la observación pública que la demuestra.
2. Usa colaboradores reales mientras sean prácticos; introduce el doble mínimo cuando necesites controlar u observar el caso.
3. Elimina afirmaciones internas y comprueba que otra implementación correcta también pasaría. La fidelidad que falte determina la integración necesaria.

Primero decide qué debe observarse; después elige con qué implementaciones puede demostrarse.

La IA no elimina las decisiones de diseño#

Una herramienta de IA puede explorar un repositorio, proponer una API, escribir tests e implementar código con rapidez. Esa velocidad no resuelve por sí sola qué comportamiento necesita el sistema. Si el encargo es ambiguo, el resultado puede ser técnicamente plausible y aun así resolver otro problema.

API-DD es compatible con este modo de trabajo porque ofrece una perspectiva para explicitar el límite de cada módulo: quién lo consume, qué mensajes intercambia, qué garantiza y qué mantiene oculto. No impone una arquitectura, un proceso ni una división entre el trabajo humano y el de la IA. Ayuda a convertir decisiones difusas en un contrato que ambos pueden revisar.

La diferencia práctica está en el criterio de éxito. «Genera el código para esta funcionalidad» invita a completar huecos por probabilidad. «Implementa esta API y demuestra estos casos» reduce la ambigüedad y permite evaluar el resultado por su comportamiento.

Pensar el sistema como APIs#

Antes de generar una implementación conviene describir las conversaciones afectadas. Para cada módulo basta con responder lo necesario:

Este mapa reduce dos fallos frecuentes. El primero es ampliar el cambio con abstracciones que nadie pidió. El segundo es copiar detalles del mecanismo en la API: nombres de una librería, estructuras de persistencia o pasos internos que luego quedan convertidos en contrato.

No todos los huecos deben rellenarse antes de empezar. Algunos se descubren al investigar el código o al escribir el primer test. Lo importante es reconocer qué es una decisión pendiente en vez de dejar que una respuesta generada la tome de forma accidental.

Los casos de prueba concretan el resultado#

Un caso de prueba expresa una diferencia observable: una entrada, una acción y un resultado, estado o mensaje que importa al consumidor. Al ejecutarlo se convierte además en feedback para la persona y para la IA.

Un buen conjunto de casos cubre las diferencias relevantes sin repetir la misma regla con datos decorativos. Por ejemplo:

dado un búfer vacío con capacidad uno
cuando se añade un valor
entonces el valor queda disponible

dado un búfer lleno
cuando se intenta añadir otro valor
entonces informa que está lleno y conserva el primero

El segundo caso es un test de contraste porque prepara una situación en la que dos comportamientos plausibles producen resultados distintos: rechazar el valor nuevo y conservar el primero, o aceptar el nuevo y reemplazar el anterior. El contraste no consiste en ejecutar las dos implementaciones a la vez; está en elegir observaciones que hagan pasar el contrato acordado y fallar la alternativa. Si el caso pasa con ambos comportamientos, no los está contrastando, aunque el test esté verde.

Estos casos dicen más que una petición genérica de «manejar errores». También dejan libertad para usar una lista, un arreglo circular u otra representación. El test protege el contrato; no dicta el recorrido interno.

Ver el test fallar antes de implementar aporta una evidencia sencilla: la prueba puede detectar la ausencia del comportamiento. Verlo pasar después confirma que esa implementación satisface el ejemplo. Ninguna de las dos señales demuestra por sí sola que el diseño esté completo, pero juntas son más fiables que aceptar código porque parece correcto.

Spec-Driven Development con la especificación en el código#

API-DD es compatible con Spec-Driven Development. En esta forma de aplicarlo, la especificación ejecutable no es un documento externo que la implementación deba interpretar: es el archivo —o el conjunto— de tests versionado junto al código de producción.

La documentación puede explicar contexto y motivaciones. La parte del contrato que debe aceptar la implementación queda en código ejecutable: API pública, casos relevantes, resultados esperados y límites. El recorrido interno queda fuera.

Esto acerca la especificación al lugar donde puede contradecirse. Si cambia la firma de la API, el test deja de compilar. Si cambia una garantía, el test falla. El repositorio conserva juntos el contrato ejecutable, la implementación y la historia de ambos.

También permite separar el trabajo según la dificultad de cada etapa:

intención + repositorio
        ↓
modelo con mayor capacidad de razonamiento
        ↓
API + casos + tests en rojo + límites explícitos
        ↓
modelo más simple, acotado por esa especificación
        ↓
implementación + tests en verde

La fase de especificación concentra la ambigüedad: hay que investigar consumidores, distinguir alternativas plausibles, decidir el vocabulario y seleccionar los casos que protegen riesgos reales. Ahí puede aportar más un modelo con mayor capacidad de razonamiento y contexto. Cuando la API y los tests ya fijan el resultado observable, una implementación rutinaria puede delegarse a un modelo más simple que reciba feedback inmediato al ejecutar la suite.

Esta separación no es una garantía ni una obligación. Un algoritmo difícil o un cambio de alto riesgo puede necesitar el modelo más capaz también durante la implementación. Y el modelo que implementa no debe modificar los tests para conseguir el verde: si descubre que el contrato es imposible, incompleto o contradictorio, debe devolver esa evidencia a la fase de especificación.

La especificación tiene además un límite deliberado: solo exige los casos y garantías que contiene. Una suite verde no demuestra comportamientos que nunca fueron representados. Por eso el trabajo más importante ocurre antes de implementar: elegir la API, las diferencias observables, los límites y las casuísticas que merecen convertirse en evidencia ejecutable.

Un reparto de trabajo útil#

El reparto cambia con el riesgo. Las personas aportan intención, prioridades y decisiones de producto o arquitectura; la IA investiga el repositorio, propone casos, implementa y ejecuta verificaciones. Las decisiones ambiguas y el resultado observable se revisan en común.

Delegar una tarea no significa delegar su criterio de aceptación. Cuanto mayor sea el impacto de una decisión, más explícita debe quedar antes de convertirla en código. En cambios rutinarios, los tests y las convenciones del repositorio pueden proporcionar casi todo ese contexto.

Un flujo posible#

Este flujo es adaptable:

1. Investiga consumidores, comportamiento actual y preguntas abiertas.
2. Define la API y expresa cada diferencia observable importante en un test que falle por la razón esperada.
3. Implementa sin reescribir la especificación ni ampliar el contrato.
4. Ejecuta las verificaciones y revisa el diff como consumidor de la API.

El ciclo puede volver atrás. Un test difícil de escribir quizá revele una API incómoda; una implementación puede mostrar que faltaba representar un resultado. Corregir el contrato en ese momento es parte del diseño, no un fracaso del proceso.

Qué suele degradar el resultado#

El resultado se degrada cuando falta el consumidor o el comportamiento esperado, el contexto oculta las restricciones, la IA inventa decisiones o los tests fijan el mecanismo. También cuando se adapta la prueba al código generado o se da el cambio por terminado sin ejecutar las verificaciones reales.

La solución no es escribir un prompt enorme. Es entregar contexto seleccionado: contrato, casos, límites, convenciones y comandos de verificación. Los apéndices ofrecen plantillas breves para investigar y acordar el contrato y para implementar y verificarlo.

Ejemplo en Go#

El test describe el contrato de un búfer con capacidad uno. La implementación no está incluida a propósito: podría ser escrita por una persona o generada con IA y seguiría siendo evaluada por las mismas observaciones.

import "testing"

func TestBoundedBufferContract(t *testing.T) {
    buffer := NewBoundedBuffer[int](1)

    if got := buffer.Push(7); got != Stored {
        t.Fatalf("expected Stored, got %v", got)
    }
    if got := buffer.Push(8); got != Full {
        t.Fatalf("expected Full, got %v", got)
    }

    value, ok := buffer.Pop()
    if !ok || value != 7 {
        t.Fatalf("expected first value, got %v, %v", value, ok)
    }
}

El caso fija capacidad, respuesta y conservación del primer valor. No fija clases auxiliares, número de llamadas ni estructura interna. Esa libertad permite que la IA proponga una implementación y que el equipo la cambie después sin alterar el contrato.

Qué mejora en el código esperado#

Pensar en APIs y casos de prueba estrecha el espacio de soluciones sin elegir de antemano el mecanismo. La IA recibe nombres con significado, límites concretos y ejemplos ejecutables; el equipo recibe una forma objetiva de revisar el resultado.

El beneficio no es que todo código generado sea correcto. Es que deja de evaluarse solo por su apariencia: debe respetar el contrato, superar los casos acordados y conservar la libertad interna del módulo.

La IA acelera una propuesta; el contrato y las pruebas permiten decidir si esa propuesta sirve.

Preguntas diferentes#

API-DD no reemplaza estos enfoques. Pueden combinarse cuando cada uno conserva su pregunta principal.

No hace falta adoptar los cuatro. La tabla sirve para evitar que una técnica responda preguntas que no le corresponden.

DDD aporta significado#

DDD ayuda a descubrir conceptos, invariantes, lenguaje y límites de modelo. Cuando dos áreas utilizan una palabra parecida, permite decidir si comparten significado o necesitan representaciones distintas.

API-DD puede aprovechar ese resultado para diseñar las conversaciones que los consumidores necesitan. No decide por sí solo cuál es el modelo correcto ni requiere que el trabajo empiece por DDD.

La referencia utilizada aquí es DDD Reference de Eric Evans.

La arquitectura hexagonal orienta conversaciones#

Un port representa una conversación con propósito; los adaptadores conectan mecanismos concretos a ella. Desde API-DD, ese port puede mirarse como una API: mensajes, vocabulario, garantías y efectos.

No todo módulo necesita convertirse en un port. Dos módulos internos pueden colaborar mediante una API local sin representar un límite arquitectónico de la aplicación. Convertir cada relación en port añadiría visibilidad y sustitución sin una necesidad real.

La intención original de puertos y adaptadores está descrita por Alistair Cockburn en Hexagonal Architecture.

TDD guía la construcción#

TDD aporta el ciclo de feedback: elegir el siguiente comportamiento, escribir un test que falle, implementarlo y refactorizar. API-DD ayuda a formular ese comportamiento como una garantía observable de un módulo.

garantía del contrato → rojo → verde → refactor

El test puede descubrir que el contrato estaba incompleto. En ese caso se revisa la decisión antes de continuar; no se fuerza la implementación para conservar una especificación equivocada.

El ciclo se apoya en la descripción de TDD de Martin Fowler, basada en el trabajo de Kent Beck.

Ejemplo en Go#

Supongamos que un módulo necesita guardar y recuperar bytes por clave. Esta API puede actuar como port de salida cuando existen proveedores intercambiables.

type Key string
type Value []byte

type Store interface {
    Load(Key) (Value, bool, error)
    Save(Key, Value) error
}

La arquitectura hexagonal orienta esta dependencia hacia la necesidad del consumidor. API-DD ayuda a hacer visibles decisiones como qué significa ausencia, quién posee los bytes devueltos y qué errores deben distinguirse. TDD permite implementar esas garantías una a una. Si nunca habrá otro proveedor ni un límite relevante, una interfaz separada puede ser innecesaria.

Confusiones frecuentes#

¿Toda API es un port?#

No. Todo port ofrece una API, pero una API también puede existir entre módulos internos que no cruzan el límite de la aplicación.

¿Todo módulo necesita una interfaz del lenguaje?#

No. Una API puede expresarse mediante un tipo concreto, funciones, métodos o mensajes. Una interface técnica aporta cuando un consumidor necesita sustitución o desacoplamiento, no como requisito ceremonial.

¿API-DD prescribe un orden de diseño?#

No. Se puede empezar por cualquier módulo, regla o conversación cuyo contrato y riesgo estén claros. API-DD ofrece una perspectiva para revisar cada módulo como una API, sin prescribir una dirección temporal para descubrir el sistema.

¿Un test con varios módulos deja de ser unitario?#

La cantidad de objetos o módulos no determina qué riesgo cubre la prueba. Resulta más útil declarar la API observada y qué implementaciones participan que discutir una etiqueta universal.

¿Observar un mensaje saliente rompe la caja negra?#

No cuando ese mensaje forma parte del efecto prometido. Sí cuando se comprueba una colaboración interna que otra implementación correcta podría resolver de manera distinta.

Una secuencia práctica#

Aclara conceptos y límites con el modelado disponible. Después identifica las conversaciones entre módulos, expresa sus garantías mediante APIs y tests, e implementa en ciclos pequeños sin alterar el contrato.

El trabajo real no será lineal. Un nombre descubierto durante un test puede cambiar el modelo; una restricción arquitectónica puede obligar a revisar la API. La separación de preguntas sirve para entender la decisión, no para imponer fases rígidas.

DDD aclara el significado, la arquitectura orienta las relaciones, TDD guía el cambio y API-DD ayuda a diseñar la conversación.