Diseñar API estables: contrato primero, errores coherentes, añadir en lugar de modificar

Principios para interfaces que duran: ley de Hyrum, una sola versión, contrato primero, errores uniformes, validación en fronteras, cambios aditivos, nombres predecibles. Patrones REST y de tipos.

MetodologíametodologiaAPIarchitetturaingegneria del software19 de noviembre de 2026 · 3 min de lectura

Una API es una promesa. En cuanto alguien la usa, esa promesa cuesta cambiarla. Diseñar una interfaz estable significa decidir con cuidado qué se promete y qué se deja libre.

Dos leyes que tener presentes

La ley de Hyrum. Con un número suficiente de usuarios, todo comportamiento observable del sistema acabará siendo usado por alguien, aunque no esté documentado. Un orden aleatorio de elementos que «siempre funciona igual» se convertirá en una dependencia. Consecuencia: lo que no quieras mantener, no dejes que se filtre.

La regla de una sola versión. Evitar obligar a los clientes a elegir entre versiones distintas de la misma cosa. Cuando se puede, el sistema tiene una versión actual y los cambios se hacen de forma compatible.

Cinco principios

1. El contrato primero. Se define primero la interfaz (campos, tipos, errores, ejemplos) y después se construye. Quien usa la API puede empezar a trabajar sobre el contrato antes de que exista el código, y las discusiones ocurren cuando cuestan poco.

2. Errores con una semántica coherente. Cada error tiene la misma forma en toda la API: un código estable, un mensaje comprensible y, donde haga falta, el campo implicado. Una API en la que cada punto de entrada señala los errores a su manera es una API difícil de usar.

3. Validar en las fronteras. Se controlan las entradas donde entran en el sistema, no en cada función interna. Dentro se puede confiar en los datos ya validados.

4. Preferir añadir a modificar. Añadir un campo opcional no rompe a nadie; cambiar su significado o quitarlo, sí. Los cambios incompatibles se tratan como un evento con aviso previo.

5. Nombres predecibles. Las mismas palabras para las mismas cosas, el mismo estilo en todas partes. Quien haya aprendido un punto de entrada debería adivinar los demás.

Patrones para las API REST

  • Recursos. Se modelan sustantivos (pedidos, clientes), no verbos; las acciones son los métodos del protocolo.
  • Paginación. Toda lista puede crecer: se prevé desde el principio, con un cursor o un índice.
  • Filtros. Parámetros explícitos y documentados, con valores por defecto razonables.
  • Actualizaciones parciales. Una actualización parcial modifica solo los campos enviados y no pone a cero los demás.

Patrones para los tipos

  • Uniones discriminadas para las variantes: un campo que dice de qué tipo se trata y los campos que existen solo para ese tipo.
  • Separación entre entrada y salida. Lo que el cliente envía no coincide con lo que recibe (el identificador lo asigna el sistema).
  • Tipos distintos para los identificadores. Un identificador de cliente no debe poder pasarse donde hace falta uno de pedido.

Señales de alarma

  • La interfaz definida a posteriori, describiendo el código.
  • Errores con formas distintas en puntos distintos.
  • Validaciones dispersas dentro de la lógica en lugar de en las fronteras.
  • Campos eliminados o renombrados sin aviso.
  • Comportamientos no documentados en los que ya se apoyan los clientes.
  • Listas sin paginación.

Un ejemplo

Una API devuelve el importe como número y un día se quiere acompañar de la divisa. Cambiar el tipo del campo rompe a los clientes. Añadir un campo nuevo «divisa» junto a «importe» no rompe a nadie; la eventual retirada del formato antiguo se anuncia con un periodo de transición.

Cuándo usarlo

Al diseñar API, fronteras entre módulos o cualquier interfaz pública; al crear puntos de entrada REST o GraphQL; al definir los contratos de tipos entre módulos o entre frontend y backend.

Este método deriva de la familia de skills de código abierto agent-skills de Addy Osmani (licencia MIT), reescrita y adaptada.

Este artículo es una skill de OIAR

Lo que acabas de leer es el contenido de una skill del catálogo de OIAR, escrito para las personas. Un conocimiento como este pero más rico y profundo, escrito para los agentes, guía las entrevistas, el análisis y el informe dentro de la plataforma. Las skills se usan en OIAR: para probarla en un proyecto tuyo necesitas una cuenta.

api-and-interface-designMétodo para diseñar API e interfaces estables: contrato primero, errores coherentes, validación en las fronteras, cambios aditivos, nombres predecibles, patrones REST (recursos, paginación, filtros, PATCH) y de tipos (uniones discriminadas, entrada y salida separadas, identificadores distintos). Úsese al diseñar API o fronteras entre módulos.