Ir al contenido

API Design Patterns: una integración es un contrato, no un favor

JJ Geewax · Manning, 2021
3 de octubre de 2025 por
API Design Patterns: una integración es un contrato, no un favor
Andrés Briñez

Geewax escribe desde Google y desde el diseño orientado a recursos: en lugar de inventar verbos, se nombran cosas y se les aplican unas pocas operaciones estándar. Sobre esa base va resolviendo los problemas que aparecen siempre: cómo se actualiza un campo sin pisar los demás, qué devuelve una operación que tarda diez minutos, cómo se paginan cien mil registros, cómo se borra algo que otro todavía referencia.

Qué hice con él

Cambió cómo escribo la parte de integraciones de un mapa de arquitectura. Antes describía sistemas conectados con flechas; ahora cada flecha lleva el contrato: qué recurso, qué operaciones, quién es el dueño del dato y qué pasa cuando el otro lado no responde. Una flecha sin contrato es un deseo dibujado.

La regla de compatibilidad es la que más discusiones me ahorra. Agregar un campo es seguro; quitarlo, renombrarlo o cambiar lo que significa no lo es, por mucho que «nadie lo usa». En una empresa siempre hay un archivo de Excel conectado que nadie recuerda haber hecho.

Y la de las operaciones largas cambió lo que prometo: un proceso que tarda —una carga masiva, una consulta a un organismo externo, una conciliación— no devuelve el resultado, devuelve algo que se puede consultar después. Modelar eso desde el principio evita la peor conversación posible, la de la pantalla congelada.

Qué dejé fuera

El nivel de ceremonia. Estas pautas se escribieron para interfaces que usan miles de equipos durante años; un integrador entre dos sistemas de una empresa mediana no necesita todo el aparato, y aplicarlo entero se vuelve un costo que el cliente paga sin recibir nada. Tomo el vocabulario y las reglas de compatibilidad, y dejo el resto en el estante.

AI-Powered Business Intelligence: escrito antes del terremoto, y aun así útil
Tobias Zwingmann · O'Reilly, 2022
WhatsApp