Diseñar APIs que envejecen bien

Las mejores APIs parecen obvias en retrospectiva. Llamas a un método, hace la única cosa que su nombre promete y se sigue comportando así a lo largo de una docena de versiones. Esa fiabilidad no es suerte. Es el resultado de un puñado de decisiones tomadas temprano y defendidas con el tiempo.

Nombra las cosas para quien las llama, no para la implementación

Una API es una promesa escrita en nombres de métodos. Cuando nombras una función según cómo funciona internamente, cada refactorización amenaza con romper esa promesa. Nómbrala según lo que quiere quien la llama, y la implementación queda libre para cambiar por debajo.

La prueba es simple: lee el lugar de la llamada en voz alta. Si un nuevo compañero de equipo puede adivinar qué ocurre sin abrir el código fuente, el nombre está cumpliendo su función.

Haz que el caso común sea sin esfuerzo

La mayoría de quienes llaman quieren lo mismo la mayor parte del tiempo. Diseña la ruta por defecto para que no requiera configuración, y luego añade opciones por encima para los casos raros. Una API que exige cinco parámetros para una tarea rutinaria será envuelta en un ayudante por el primer equipo que la use, y ahora mantienes dos interfaces en lugar de una.

Cada argumento obligatorio es un pequeño impuesto que cobras en cada llamada. Cóbralo solo cuando el valor genuinamente no pueda inferirse.

Versiona el contrato, no el código

Los cambios que rompen la compatibilidad no son el enemigo. La sorpresa sí lo es. Cuando debas romper algo, dale un nuevo nombre o una nueva versión y deja que la ruta antigua siga funcionando durante una ventana de obsolescencia clara. Quienes llaman perdonarán una migración que puedan planificar. No perdonarán un cambio silencioso que rompe la producción un martes.

Una API que envejece bien es una en la que puedes dejar de pensar. Constrúyela de modo que quienes dependen de ella también puedan hacerlo.