Una API no es compatible solo porque conserve la misma ruta o versión. Sus consumidores dependen también de la forma de los datos, las reglas de validación, los valores predeterminados y el comportamiento ante errores. Si distintos clientes se actualizan a ritmos diferentes, un cambio que parece pequeño para quien mantiene el servidor puede interrumpir una aplicación móvil, una integración de terceros o un proceso interno.
Una política de compatibilidad de datos en APIs PHP convierte ese riesgo en decisiones explícitas: qué cambios se aceptan, cómo se despliegan y qué pruebas deben superarse antes de retirar un contrato. No existe una regla universal que haga compatible cualquier cambio; hay que considerar cómo cada consumidor lee y envía los datos.
El contrato incluye datos, validación y comportamiento
El contrato de una API abarca más que el esquema documentado. Incluye los campos y sus tipos, si pueden omitirse o ser nulos, cómo se interpretan fechas e importes, qué valores acepta una solicitud, el formato de los errores y las garantías sobre la respuesta. También comprende reglas observables como el orden de una colección cuando los clientes dependen de él, o la estabilidad de un identificador.
En PHP, los objetos de transferencia, los validadores y los serializadores suelen materializar partes de ese contrato. Revisar solo el controlador puede dejar cambios incompatibles ocultos en una regla de validación, un recurso de respuesta o un mapeo entre el modelo y la API. Conviene documentar el contrato a partir de lo que el cliente realmente observa, no de la estructura interna de las clases o tablas.
Clasificar cambios según el consumidor
La clasificación es una herramienta de evaluación, no una garantía automática. Un cambio aditivo suele mantener el funcionamiento de clientes que ignoran campos desconocidos, pero puede romper consumidores que convierten la respuesta a una estructura estricta o validan contra un esquema cerrado. Del mismo modo, un nuevo campo opcional en una solicitud puede ser inocuo para clientes antiguos, mientras que hacerlo obligatorio no lo es.
- Normalmente aditivos: añadir un campo opcional a una solicitud o respuesta, o añadir un valor a una colección, siempre que los consumidores toleren esos elementos.
- Potencialmente incompatibles: eliminar o renombrar un campo, cambiar su tipo, volver obligatorio uno opcional, alterar el formato de un error o modificar el significado de un valor existente.
- Dependientes del contexto: cambiar el orden, la precisión numérica, la zona horaria, la semántica de un estado o los criterios de paginación. Aunque el esquema no cambie, el resultado puede cambiar para el cliente.
Antes de aprobar un cambio, identifique consumidores y revise cómo procesan el dato. Un campo desconocido puede ignorarse, provocar un error de validación o quedar expuesto a una lógica que no lo esperaba. No asuma que todos los lenguajes, bibliotecas o versiones de cliente reaccionan igual.
Evolucionar solicitudes y respuestas con cautela
En las respuestas, añadir un campo es más seguro si se conserva la posibilidad de que clientes estrictos rechacen propiedades adicionales. Si un campo cambia de significado o tipo, no lo reutilice silenciosamente. Introduzca un campo nuevo con semántica clara, documente su relación con el anterior y mantenga ambos durante una transición definida.
En las solicitudes, distinguir entre ausente, nulo y vacío es esencial. En PHP, una validación que trata la ausencia de una clave igual que su valor null puede borrar datos o aplicar valores predeterminados inesperados. Defina qué significa cada caso y pruebe tanto clientes nuevos como antiguos. Para un campo nuevo, considere aceptar su ausencia inicialmente y asignar un comportamiento compatible, en vez de exigirlo desde el primer despliegue.
Versionar rutas no es la única opción. Se puede evolucionar un contrato manteniendo la ruta si los cambios son compatibles, o publicar una versión nueva cuando no lo sean y la coexistencia tenga sentido operativo. En ambos casos, documente la política de soporte: una etiqueta de versión, por sí sola, no informa cuánto tiempo seguirá disponible un contrato.
Desplegar base de datos y API por fases
Un despliegue seguro separa los cambios de almacenamiento de la exposición del nuevo comportamiento. Una secuencia habitual es ampliar el esquema, desplegar código que pueda operar con la estructura anterior y la nueva, migrar datos si hace falta y, finalmente, activar la lectura o escritura nueva. La retirada de columnas o caminos antiguos llega después, cuando hay evidencia suficiente de que dejaron de ser necesarios.
Este enfoque de expansión y contracción evita que una versión de la aplicación espere una columna que todavía no existe o que un despliegue nuevo deje de funcionar con procesos antiguos. En sistemas con varias instancias o trabajadores en segundo plano, tenga en cuenta que pueden convivir distintas versiones del código durante el despliegue. Las migraciones deben ser compatibles con esa convivencia y contar con una estrategia de recuperación si falla una fase.
La exposición gradual —por ejemplo, habilitar una capacidad para una parte controlada de los consumidores— puede limitar el impacto, pero no equivale a una divulgación pública ni sustituye la compatibilidad. Use controles de activación cuando permitan observar y revertir el comportamiento; defina de antemano qué condiciones detienen la expansión.
Medir uso sin registrar datos sensibles
Para saber qué consumidores siguen usando un contrato, la telemetría debe identificar la versión o capacidad relevante sin almacenar cuerpos de solicitud o respuesta que contengan información personal, credenciales o datos comerciales. Registre señales mínimas, como ruta, versión declarada del cliente, resultado y fecha; limite el acceso y la retención según las necesidades operativas y las obligaciones aplicables.
La señal debe ser útil para decidir. Distinga solicitudes de usuarios reales de pruebas, reintentos o tráfico automatizado; observe también errores, latencia y cambios en el volumen. Si no existe un identificador fiable de cliente, no deduzca su identidad a partir de datos sensibles. Reconozca que proxies, claves compartidas y clientes que no envían versión pueden dejar zonas sin visibilidad.
Retirar un contrato con criterios verificables
No retire una versión solo porque haya pasado un plazo anunciado. Defina señales y umbrales acordes con el riesgo: ausencia sostenida de tráfico identificable, migración confirmada de integraciones conocidas, estabilidad de la versión sucesora y un procedimiento de soporte para excepciones. Si persiste tráfico desconocido, investigue antes de interpretar la falta de identificación como falta de uso.
Comunique con antelación qué cambia, a quién afecta, cuál es la alternativa, las fechas previstas y cómo probar la migración. Mantenga la información en documentación accesible a los equipos consumidores y establezca un canal para reportar incompatibilidades. Si el impacto no se puede revertir rápidamente, considere una transición más larga o la coexistencia temporal de contratos.
Lista de comprobación antes de publicar
- ¿Se documentaron los campos, tipos, nulabilidad, valores predeterminados y errores afectados?
- ¿Se comprobó el comportamiento de clientes tolerantes y estrictos ante campos nuevos o ausentes?
- ¿Las pruebas de contrato cubren consumidores conocidos y casos límite de validación?
- ¿La migración de base de datos permite convivir con versiones anteriores de la aplicación?
- ¿Hay métricas suficientes para detectar errores y uso del contrato sin capturar datos sensibles?
- ¿Se definieron responsables, comunicación, criterios de reversión y condiciones para retirar lo antiguo?
Una política útil no promete que ningún cambio romperá a ningún cliente. Hace explícitos los supuestos, limita las sorpresas y permite actuar con evidencia. Revise estas decisiones en cada cambio de contrato, especialmente cuando la API tenga consumidores externos cuyo ciclo de actualización no controla el equipo.
