Team API: cómo se usa a tu equipo sin tener que preguntarle

Todo equipo tiene una interfaz. Existe aunque nadie la haya escrito: es el conjunto de suposiciones que el resto de la organización tiene sobre cómo pedirle algo, qué esperar y cuánto va a tardar.

Cuando esa interfaz no está escrita, se transmite por vía oral y con una tasa de error alta. La gente pregunta a quien conoce, ese alguien contesta desde su propio entendimiento, y el resultado es que cada solicitud llega distinta, por un canal distinto, con información incompleta, y el equipo dedica una fracción sustancial de su tiempo a aclarar en vez de a trabajar.

El concepto de Team API resuelve esto con un artefacto de una página.

Qué contiene

Una Team API responde ocho preguntas que hoy se responden por conversación:

Propósito. Qué existe para lograr este equipo, en una frase entendible para alguien de otra área.

Qué provee. Los servicios, componentes, datos o capacidades de los que es dueño. Con nombres concretos.

Cómo se le pide algo. El canal, el formato, la información mínima que necesita una solicitud para ser procesable. Este punto por sí solo elimina buena parte de la fricción cotidiana.

Qué decide solo. Las decisiones que el equipo toma sin consultar. Explicitarlo evita tanto el escalamiento innecesario como la sorpresa de descubrir que alguien decidió algo que otros creían compartido.

Qué requiere acuerdo. Las decisiones que involucran a otros y con quién.

Compromisos de servicio. Qué tiempos de respuesta y qué disponibilidad son razonables. No como contrato legal, sino como expectativa explícita.

De qué depende. Los otros equipos, sistemas o proveedores sin los cuales no puede operar.

Dónde está su documentación. Un enlace, no una promesa.

Los tres modos de interacción

La Team API se vuelve mucho más útil cuando se combina con una idea complementaria: no todas las relaciones entre equipos son del mismo tipo. Team Topologies las clasifica en tres modos, y confundirlos es una fuente frecuente de frustración.

Colaboración. Dos equipos trabajan juntos, de forma intensa y con límites difusos, para resolver algo nuevo que ninguno entiende del todo. Es costoso y debe ser temporal. Su valor está en el descubrimiento conjunto; su costo, en que ambos equipos pierden autonomía mientras dura.

Servicio. Un equipo consume lo que otro provee, a través de una interfaz definida, sin necesidad de conversación. Es el modo más eficiente y al que hay que tender para todo lo que ya se entiende bien.

Facilitación. Un equipo ayuda a otro a adquirir una capacidad, con el objetivo explícito de dejar de ser necesario. Es temporal por diseño.

El diagnóstico útil aparece al preguntar, para cada relación entre equipos, en qué modo está y en qué modo debería estar. El patrón más común es una relación que empezó como colaboración legítima —había algo nuevo que resolver— y se quedó ahí para siempre, consumiendo atención de ambos lados en algo que ya está entendido y podría ser un servicio.

El costo de no tener interfaz

Vale la pena nombrar lo que se paga cuando cada equipo es una caja negra que hay que descifrar conversando.

La carga de coordinación se distribuye mal. Las personas más conocidas o más accesibles reciben la mayoría de las consultas, independientemente de si son las indicadas. Esa concentración es invisible en cualquier reporte y muy real en la carga de esas personas.

El conocimiento sobre cómo trabajar con un equipo vive en la red informal. Quien lleva tres años sabe a quién preguntarle; quien llegó hace tres meses no. Eso alarga la incorporación y hace que la productividad de una persona nueva dependa de su capacidad de construir relaciones en vez de de su competencia.

Y las solicitudes llegan mal formuladas, lo que produce ciclos de aclaración que consumen más tiempo total que el trabajo mismo.

Escribirla es el ejercicio, no el documento

El valor de una Team API no está principalmente en el documento resultante. Está en las discusiones que hay que tener para escribirlo.

Escribir “qué decide solo” obliga al equipo a acordar internamente qué decide solo, y con frecuencia descubre que sus integrantes tenían ideas distintas. Escribir “de qué depende” hace visible una dependencia que nadie había nombrado. Escribir “compromisos de servicio” fuerza una conversación honesta sobre capacidad que suele estar pendiente.

Por eso conviene que la escriba el equipo, no alguien externo, y que se revise con dos o tres de sus consumidores principales. Esa revisión cruzada casi siempre revela una brecha entre lo que el equipo cree que provee y lo que sus consumidores creen que pueden pedirle.

Los errores al escribirla

Hay cuatro formas típicas de escribir una Team API que no sirve, y las cuatro son reconocibles.

Escribirla en lenguaje interno. El propósito dice algo como “operamos la capa de orquestación de eventos del dominio transaccional”. Quien la lee desde comercial o desde operaciones no entiende qué puede pedirle a ese equipo, que era exactamente lo que el documento debía resolver. La prueba: si alguien de otra área no puede explicar con sus palabras qué hace el equipo después de leerlo, hay que reescribirlo.

Prometer más de lo que se puede sostener. Los compromisos de servicio se escriben con optimismo, en el mejor escenario, sin considerar la carga real ni las interrupciones. A los dos meses no se cumplen, y un compromiso incumplido genera más fricción que la ausencia de compromiso, porque ahora hay una expectativa formal que reclamar.

Omitir lo que el equipo no hace. Es tan importante como lo que hace. Un equipo que no declara sus límites recibe solicitudes fuera de alcance de forma indefinida, y cada una consume tiempo en explicar por qué no corresponde.

Escribirla una vez y no volver a mirarla. El documento describe la organización de hace dieciocho meses. Alguien la lee, actúa según lo que dice, y descubre que ya no es así. Una Team API desactualizada es peor que ninguna, porque genera confianza mal fundada.

Hay un quinto error más sutil: escribirla desde el punto de vista del equipo en vez del consumidor. La estructura interna del equipo, cómo se organiza, qué roles tiene, es información que al consumidor no le sirve. Lo que le sirve es qué puede pedir, cómo, y qué va a recibir.

Una forma práctica de evitarlo es escribir el documento respondiendo a preguntas reales que el equipo ya recibió. Revisar las últimas veinte consultas que llegaron desde afuera y asegurarse de que el documento las responde todas. Eso garantiza que está escrito en el vocabulario de quien pregunta y que cubre lo que efectivamente se pregunta, en vez de lo que el equipo cree que debería preguntarse.

Mantenerla viva

Un documento de este tipo se degrada si no tiene un momento de revisión. Lo más simple que funciona: revisarla cuando cambia algo relevante —una responsabilidad nueva, una dependencia que desaparece, un cambio de dueño— y una vez por trimestre por defecto.

Y ubicarla donde la gente la va a encontrar: junto al código, en el catálogo de servicios, en el mismo lugar donde está el resto de la documentación técnica. Una Team API en una carpeta compartida que nadie visita es equivalente a no tenerla.

Hay una prueba final para saber si funciona. Pídele a alguien que se incorporó hace un mes que use la Team API de otro equipo para hacer una solicitud real, sin preguntarle a nadie. Si lo logra, el documento sirve. Si tiene que preguntar, todavía falta.