Regla

Evite romper público API pública.
Cambia a público API públicos que podría romper
existente cliente solicitudes son rompiendo cambios.
Piense en en la API contrato como a promesa - cambiando
en después de clientes dependen de que se rompe su código.

Lenguajes soportados: PHP, Java, C#, Python, JavaScript, TypeScript

Introducción

Las API públicas son contratos entre su servicio y sus consumidores. Una vez que los clientes dependen del formato de solicitud, la estructura de respuesta o el comportamiento de un endpoint, cambiarlo rompe su código. Los cambios disruptivos obligan a todos los clientes a actualizarse simultáneamente, lo cual a menudo es imposible cuando no se controlan los clientes. Las aplicaciones móviles no pueden ser actualizadas forzosamente, las integraciones de terceros necesitan tiempo de migración y los sistemas heredados pueden no actualizarse nunca.

Por qué es importante

Interrupción del cliente y confianza: Los cambios de API que rompen la compatibilidad causan fallos inmediatos en las aplicaciones cliente en producción. Los usuarios experimentan errores, pérdida de datos o interrupciones completas del servicio. Esto daña la confianza entre proveedores y consumidores de API, y viola el contrato implícito de que las API estables permanecen estables.

Costes de coordinación: Coordinar cambios disruptivos entre múltiples equipos de clientes es costoso y lento. Cada equipo necesita tiempo para actualizar el código, probar los cambios y desplegar. Para APIs públicas con clientes desconocidos (aplicaciones móviles, integraciones de terceros), la coordinación es imposible.

Proliferación de versiones: Los cambios disruptivos mal gestionados llevan a mantener múltiples versiones de API simultáneamente. Cada versión requiere rutas de código, pruebas, documentación y correcciones de errores separadas, multiplicando exponencialmente la carga de mantenimiento.

Ejemplos de código

❌ No conforme:

// Version 1: Original API
app.get('/api/users/:id', async (req, res) => {
    const user = await db.users.findById(req.params.id);
    res.json({ id: user.id, name: user.name });
});

// Version 2: Breaking change - renamed field
app.get('/api/users/:id', async (req, res) => {
    const user = await db.users.findById(req.params.id);
    res.json({
        id: user.id,
        fullName: user.name  // Breaking: 'name' renamed to 'fullName'
    });
});

Por qué está mal: Renombrar 'name' a 'fullName' rompe todos los clientes existentes que esperan el campo 'name'. El código del cliente que acceda a response.name recibirá 'undefined', causando errores. Este cambio obliga a todos los clientes a actualizarse simultáneamente o fallar.

✅ Conforme:

// Version 2: Additive change - keeps old field, adds new
app.get('/api/users/:id', async (req, res) => {
    const user = await db.users.findById(req.params.id);
    res.json({
        id: user.id,
        name: user.name,           // Keep for backward compatibility
        fullName: user.name        // Add new field (deprecated 'name')
    });
});

// Or use API versioning
app.get('/api/v2/users/:id', async (req, res) => {
    const user = await db.users.findById(req.params.id);
    res.json({ id: user.id, fullName: user.name });
});

¿Por qué esto importa? Manteniendo lo antiguo nombre el campo mantiene la compatibilidad con versiones anteriores mientras añade nombre completo para nuevos clientes. Alternativamente, creando un nuevo endpoint versionado (/api/v2/) permite cambios disruptivos sin afectar a los clientes existentes que aún utilizan /api/v1/.

Conclusión

Evolucione las APIs mediante cambios aditivos: añada nuevos campos, nuevos endpoints, añada parámetros opcionales. Cuando los cambios disruptivos sean inevitables, utilice el versionado de API para ejecutar versiones antiguas y nuevas de forma concurrente. Depreque campos antiguos con plazos claros y guías de migración antes de eliminarlos.