𝟵 𝗔𝗣𝗜 𝗖𝗵𝗮𝗻𝗴𝗲𝘀 𝗧𝗵𝗮𝘁 𝗕𝗿𝗲𝗮𝗸 𝗬𝗼𝘂𝗿 𝗔𝗽𝗽

𝟵 𝗖𝗮𝗺𝗯𝗶𝗼𝘀 𝗲𝗻 𝗹𝗮 𝗔𝗣𝗜 𝗾𝘂𝗲 𝗥𝗼𝗺𝗽𝗲𝗻 𝘁𝘂 𝗔𝗽𝗹𝗶𝗰𝗮𝗰𝗶ó𝗻

"No rompimos nada. Solo limpiamos la respuesta."

Esas palabras suelen provocar fallos. Una aplicación móvil deja de funcionar. Una integración con un socio devuelve basura. Has cambiado la estructura de los datos de los que otros dependen.

Los cambios peligrosos a menudo parecen una limpieza. Superan las revisiones de código y las pruebas. La rotura ocurre en código que no puedes ver.

Aquí tienes nueve cambios que parecen seguros, pero no lo son.

• Renombrar campos Cambiar userId por user_id por consistencia rompe los clientes. Renombrar es borrar y añadir. La parte del borrado es la que afecta a los usuarios. Movimiento seguro: Añade el nuevo campo. Mantén el antiguo. Decláralo como obsoleto. Elimínalo mucho después.

• Hacer que un campo sea opcional Un campo solía estar siempre presente. Ahora, a veces es null. El código del cliente falla cuando intenta procesarlo. Movimiento seguro: Trata el "siempre presente" como una promesa. Si un campo pasa a ser opcional, utiliza una nueva versión.

• Eliminar campos no utilizados No puedes ver cómo tus consumidores utilizan tus datos. "No utilizado" solo significa que no lo utilizas tú. Movimiento seguro: Mide el uso de los campos en producción antes de eliminar nada.

• Reducir los tipos de entrada Cambiar un string por un enum o un número por un entero rompe las peticiones. Ampliar una entrada es seguro. Reducirla es un cambio disruptivo. Movimiento seguro: Solo flexibiliza las entradas que aceptas. Restringirlas requiere una nueva versión.

• Cambiar los valores por defecto Cambiar un valor por defecto de false a true cambia el comportamiento sin generar un error. Esto rompe la lógica de forma silenciosa. Movimiento seguro: Trata un cambio de valor por defecto como un cambio disruptivo.

• Añadir campos obligatorios Añadir tenantId y hacerlo obligatorio rompe a todos los clientes existentes. Recibirán un error 400. Movimiento seguro: Los campos nuevos deben ser opcionales o utilizar una nueva versión.

• Cambiar los formatos de error Cambiar un 400 por un 422 o cambiar el cuerpo del error rompe el código de gestión de errores. Movimiento seguro: Los formatos de error son contratos. Versiónalos como cualquier otra cosa.

• Modificar los valores de un enum Renombrar "active" a "ACTIVE" rompe los clientes. Eliminar un valor rompe a los clientes con lógica estricta. Movimiento seguro: Los valores de un enum son para siempre. Añádelos con cuidado. Nunca los renombres ni los elimines sin una versión mayor.

• Cambiar el significado de los datos Cambiar una fecha de segundos Unix a ISO-8601 o cambiar la paginación de offset a cursor lo rompe todo. Es posible que una diferencia de esquema ni siquiera detecte esto. Movimiento seguro: Fija los formatos de forma explícita. Compara los payloads reales, no solo la especificación.

No confíes en tu intuición. Compara cada cambio con el contrato de producción en tu CI. Un humano podría pasar por alto un campo renombrado. Una herramienta de diff no lo hará.

Fuente: https://dev.to/deepaksatyam/9-api-changes-that-look-backwards-compatible-but-arent-1bk0