Definition
Alguna vez has actualizado una aplicacion en tu movil y de repente algo que antes funcionaba dejo de hacerlo? Quiza un boton desaparecio o una funcion se comporta de manera completamente diferente. Esa experiencia frustrante es esencialmente lo que ocurre cuando una API hace un “cambio incompatible” o breaking change, solo que en lugar de usuarios normales, son los desarrolladores y sus aplicaciones los que se llevan el susto.
Un cambio incompatible es cualquier modificacion a una API que provoca que las aplicaciones existentes que la utilizan dejen de funcionar correctamente. Piensalo asi: si has estado enviando cartas a un amigo a una direccion especifica durante anos, y un dia se muda sin avisarte, tus cartas empezaran a volver como no entregables. El “contrato” que tenias sobre donde enviar las cosas se ha roto.
En el mundo de las APIs, estos contratos son muy precisos. Cuando los desarrolladores construyen aplicaciones que dependen de una API, escriben su codigo esperando que ciertos endpoints existan, que los datos vuelvan en un formato particular, y que los comportamientos se mantengan consistentes. Un cambio incompatible viola una o mas de estas expectativas. Puede ser algo tan dramatico como eliminar una funcionalidad completa, o tan sutil como cambiar si un campo es opcional u obligatorio. De cualquier manera, el resultado es el mismo: codigo que funcionaba perfectamente ayer, hoy falla repentinamente.
Example
Escenario Real 1: La Renovacion de Autenticacion de PayPal PayPal cambio una vez su sistema de autenticacion de simples credenciales API a tokens OAuth 2.0. Cada comerciante que habia integrado PayPal tuvo que reescribir su codigo de autenticacion, actualizar como almacenaban las credenciales y desplegar nuevas versiones de sus sistemas de pago. No era una correccion de errores ni un ajuste menor - era un cambio fundamental en como debia hacerse cada llamada a la API.
Escenario Real 2: La Reestructuracion de la API de Twitter Cuando Twitter (ahora X) reestructuro su API, muchas apps de terceros que habian funcionado durante anos de repente no podian obtener tweets, publicar actualizaciones ni acceder a informacion de usuarios. Los desarrolladores tuvieron que correr para entender los nuevos endpoints, actualizar su codigo y a veces redisenar completamente sus aplicaciones.
Escenario Real 3: Las Actualizaciones del Graph API de Facebook Facebook regularmente da de baja versiones antiguas de su Graph API. Las apps construidas sobre la version 2.0 podrian dejar de funcionar cuando esa version se retira, obligando a los desarrolladores a actualizar a la version 3.0 o posterior. Esto afecta desde botones de login hasta funciones de compartir en redes sociales en millones de sitios web.
Escenario Real 4: Los Cambios de Objetos de Pago de Stripe
Cuando Stripe cambio como se estructuraban los objetos de pago, las aplicaciones que esperaban encontrar informacion del cliente en un lugar de repente la encontraban anidada en otro sitio. Lo que antes era response.customer.email podria convertirse en response.data.customer_details.email_address, rompiendo cada fragmento de codigo que dependia de la ruta antigua.
Analogia
La Metafora de la Reforma del Hogar: Imagina que has vivido en la misma casa durante 10 anos. Sabes exactamente donde estan los interruptores de luz - puedes encenderlos en la oscuridad sin pensar. Un dia, el casero decide “modernizar” y mueve cada interruptor a nuevas ubicaciones, cambia algunos de interruptores a sensores de movimiento, y elimina algunas luces por completo. Llegas a casa esa noche y de repente no puedes moverte por tu propia casa. Eso es un cambio incompatible. Claro, quiza la nueva configuracion es “mejor”, pero nadie te aviso, y toda tu memoria muscular ahora es inutil.
La Analogia del Menu del Restaurante: Has estado pidiendo “lo de siempre” en tu restaurante favorito durante anos - un combo numero 7 que te encanta. Entonces redisenan el menu: el numero 7 ahora es algo completamente diferente, tu antiguo favorito ha sido eliminado por completo, y los elementos que solias pedir ahora estan dispersos en tres secciones diferentes del menu con nuevos nombres. El restaurante puede decir “mejoramos el menu”, pero para ti, es un caos.
El Ejemplo de la Evolucion del Lenguaje: Piensa en como los idiomas cambian con el tiempo. Si alguien del siglo XIX intentara leer un mensaje de texto de hoy, estaria perdido - no porque el idioma este “roto”, sino porque el entendimiento compartido de palabras, abreviaturas y convenciones ha cambiado. Los cambios incompatibles en APIs son similares: el “idioma” que habla la API ha cambiado, y los antiguos “hablantes” (aplicaciones existentes) ya no pueden entenderlo.
La Comparacion del Sistema de Autopistas: Imagina un sistema de autopistas donde los camiones han usado una salida especifica para entregas durante 20 anos. Un dia, la ciudad cierra esa salida permanentemente y la mueve 15 kilometros mas adelante sin actualizar los sistemas GPS ni las senales. Miles de camiones de reparto de repente no pueden completar sus rutas. La ciudad puede haber tenido buenas razones (construccion, seguridad, eficiencia), pero el cambio repentino rompe todo el sistema logistico que dependia de esa salida.
Code Example
// Ejemplos de cambios incompatibles
// ❌ Eliminar endpoint
DELETE /v1/users/{id} // Eliminado en v2
// ❌ Cambiar metodo HTTP
// v1: POST /login
// v2: GET /login // ROMPE clientes usando POST
// ❌ Cambiar estructura de respuesta
// v1
{
"products": [...]
}
// v2
{
"data": {
"products": [...]
}
} // ROMPE clientes accediendo a response.products
// ❌ Hacer obligatorio un campo opcional
// v1: POST /orders {"productId": 123}
// v2: POST /orders {"productId": 123, "quantity": 1} // quantity ahora requerido
// ❌ Cambiar formato de codigo de error
// v1: {"error": "INVALID_TOKEN"}
// v2: {"error": {"code": "AUTH001", "type": "InvalidToken"}}
// Como comunicar cambios incompatibles
[HTTP/1.1](https://reference.apios.info/es/terms/http-1-1/) 200 OK
Sunset: Sat, 31 Dec 2025 23:59:59 GMT
Deprecation: true
Link: <https://api.company.com/docs/migration/v1-to-v2>; rel="deprecation"
{
"warning": "Este endpoint sera retirado el 2025-12-31",
"migrationGuide": "https://api.company.com/docs/migration/v1-to-v2"
}