Cambiar una API sin avisar rompe apps
Versionar una API es publicar sus cambios con un número de versión para que las apps que ya la usan sigan funcionando. Documentarla es describir cada ruta, sus datos y sus errores.
Si renombras un campo sin avisar, la app de la biblioteca deja de mostrar los títulos de un día para otro.
Al terminar esta lección
Nota
Puedo documentar una API y decir si un cambio rompe a quien la usa.
Palabras clave
| Palabra | Qué significa | Ejemplo |
|---|---|---|
| Documentación | el texto que describe cada ruta, sus datos y sus errores | |
| Versión | un número que identifica una forma concreta de la API | /v1/books |
| Cambio que rompe | un cambio tras el cual una app que funcionaba falla | |
| Retrocompatible | que sigue sirviendo a quien usaba la versión anterior | |
| Obsoleto | que todavía funciona pero se retirará pronto |
Las celdas que rellenan los estudiantes quedan en blanco en esta vista previa.
Una buena documentación responde antes de que preguntes
Por cada ruta, la documentación dice el método, los datos que acepta, un ejemplo de petición y de respuesta, y los errores posibles.
Un archivo OpenAPI describe todo eso en un formato que lee un programa, y de él se generan páginas de ayuda y pruebas. La API del laboratorio publica el suyo en su dirección raíz.
La API se describe a sí misma
Prepara la tabla books y pide la raíz de la API. La respuesta es larga, así que el Run busca solo la ruta de los libros.
Dar a psql la contraseña
export PGPASSWORD=shopSe muestra aquí y no se ejecuta. Crea una cuenta gratuita para pulsar Ejecutar y escribirlo en el terminal de tu propio laboratorio.
Crear la tabla de libros
psql -h db -U shop -q -c "drop table if exists books; create table books (id serial primary key, title text not null, copies int not null default 1, status text not null default 'disponible'); insert into books (title, copies, status) values ('Redes de computadores', 3, 'disponible'), ('Algoritmos y estructuras', 0, 'prestado'), ('Sistemas operativos', 2, 'disponible'), ('Ingenieria del software', 1, 'disponible'); notify pgrst, 'reload schema'"Se muestra aquí y no se ejecuta. Crea una cuenta gratuita para pulsar Ejecutar y escribirlo en el terminal de tu propio laboratorio.
Buscar la ruta /books en la descripción
curl -s "http://api:3000/" | grep -o '"/books"' | head -n 1Se muestra aquí y no se ejecuta. Crea una cuenta gratuita para pulsar Ejecutar y escribirlo en el terminal de tu propio laboratorio.
Añadir un campo no rompe, quitarlo sí
Un cambio rompe si una app que funcionaba deja de funcionar. Añadir un campo nuevo no rompe: las apps ignoran lo que no conocen.
Quitar un campo, renombrarlo o cambiar su tipo sí rompe, porque las apps lo siguen pidiendo. Lo mismo ocurre con una ruta o con un parámetro nuevo que sea obligatorio.
Ejemplo resuelto: qué cambios rompen
| Cambio | ¿Rompe? | Por qué |
|---|---|---|
| Añadir un campo author | No | Las apps viejas lo ignoran |
| Quitar el campo copies | Sí | Las apps lo siguen leyendo |
| Renombrar title a name | Sí | El nombre viejo ya no existe |
| Cambiar copies de número a texto | Sí | Las sumas dejan de funcionar |
| Añadir un parámetro opcional | No | Quien no lo usa no nota nada |
Las celdas que rellenan los estudiantes quedan en blanco en esta vista previa.
Añadir la columna author
psql -h db -U shop -q -c "alter table books add column author text; notify pgrst, 'reload schema'"Se muestra aquí y no se ejecuta. Crea una cuenta gratuita para pulsar Ejecutar y escribirlo en el terminal de tu propio laboratorio.
Leer el libro 1 como antes
curl -s -w "\n" "http://api:3000/books?id=eq.1"Se muestra aquí y no se ejecuta. Crea una cuenta gratuita para pulsar Ejecutar y escribirlo en el terminal de tu propio laboratorio.
Renombrar title a name
psql -h db -U shop -q -c "alter table books rename column title to name; notify pgrst, 'reload schema'"Se muestra aquí y no se ejecuta. Crea una cuenta gratuita para pulsar Ejecutar y escribirlo en el terminal de tu propio laboratorio.
Pedir el campo title con su nombre viejo
curl -s -o /dev/null -w "%{http_code}\n" "http://api:3000/books?select=title"Se muestra aquí y no se ejecuta. Crea una cuenta gratuita para pulsar Ejecutar y escribirlo en el terminal de tu propio laboratorio.
Un error frecuente
Advertencia
Mucha gente cree que renombrar un campo para que quede más claro es un cambio pequeño. Para quien lo usa, es romper su app. Publica el campo nuevo en una versión nueva, y mantén el viejo mientras alguien lo pida.
Una versión nueva deja vivir a la anterior
Para un cambio que rompe, publica /v2/books y deja /v1/books funcionando. Marca la v1 como obsoleta, avisa con fecha y retírala cuando casi nadie la use.
Así cada app migra cuando puede, y no el día que tú decides.