Contratos de API
Un contrato es una promesa a un código que no controlas y no puedes arreglar. Eso es lo que diferencia los cambios de API de la refactorización interna: el coste de equivocarse lo paga otro, en un momento que tú no eliges.
Diseño
Nombra los recursos como sustantivos y deja que el método lleve el verbo. Modela la cosa, no la pantalla que actualmente la muestra — una carga útil moldeada alrededor de la interfaz de usuario de hoy se vuelve incorrecta en el próximo rediseño.
Sé deliberado sobre lo que expones. Cada campo que devuelves es un campo que debes seguir devolviendo. Los identificadores internos, las versiones de fila y los detalles de implementación filtran tu esquema en el código del llamador y lo congelan allí.
Haz que las operaciones sean idempotentes cuando el llamador pueda reintentar, que es cualquier operación accesible a través de una red. Dale al llamador una clave de idempotencia para cualquier cosa que cree o cobre, para que un reintento tras un tiempo de espera no pueda duplicarla.
Devuelve un modelo de error consistente: un código estable legible por máquina, un mensaje legible por humanos y el campo al que se refiere un fallo de validación. Los llamadores bifurcan según el código, por lo que forma parte del contrato — cambiar un código es un cambio incompatible aunque la forma no cambie.
Pagina cada lista desde la primera versión. Un endpoint que lo devuelve todo funciona hasta que la tabla crece y luego falla para el cliente con más datos. Prefiere un cursor sobre un desplazamiento cuando se insertan filas de forma concurrente.
Qué rompe a un llamador
Cambios incompatibles, independientemente de lo que permita el lenguaje del esquema:
- Eliminar o renombrar un campo, un endpoint, un método o un valor de enumeración.
- Hacer obligatorio un campo de solicitud opcional, o restringir lo que acepta un campo.
- Cambiar un tipo, incluyendo de entero a cadena y de un valor único a una lista.
- Cambiar el significado de un campo existente mientras se mantienen su nombre y tipo — el peor tipo, porque nada falla ruidosamente y los datos están silenciosamente incorrectos.
- Añadir un nuevo campo obligatorio a una solicitud.
- Cambiar un código de error, o un estado HTTP, para una condición existente.
- Restringir un valor predeterminado, o cambiar lo que sucede cuando se omite un campo.
Cambios seguros: añadir un campo opcional de solicitud, añadir un campo de respuesta, añadir un nuevo endpoint o método, añadir un valor de enumeración solo si cada consumidor ya tolera valores desconocidos — verifica eso en lugar de asumirlo.
En protobuf, nunca reutilices o renumeres una etiqueta de campo, y reserva la etiqueta y el nombre cuando elimines un campo. Una etiqueta reutilizada decodifica datos antiguos en el nuevo campo y los corrompe silenciosamente.
Cambiar un contrato de forma segura
Añade antes de eliminar y deja que ambos funcionen durante al menos una versión:
- Añade el nuevo campo o método junto al antiguo.
- Escribe ambos, lee el nuevo con una reutilización al antiguo.
- Migra a los consumidores y confirma que cada uno se ha movido.
- Elimina la ruta antigua en una versión posterior.
Versiona cuando el recurso cambie genuinamente de significado, no por cada adición. Una versión por cambio multiplica la superficie que debes mantener viva.
Orden de despliegue
El código generado y los servidores se despliegan por separado, y el espacio entre ellos es donde viven las interrupciones. Despliega primero el lado que tolera ambas formas: consumidores que aceptan el nuevo campo antes de que los productores lo emitan, productores que aceptan la nueva solicitud antes de que los llamadores la envíen.
Cuando un esquema se comparte a través de una puerta de enlace, un proxy o clientes generados, cada componente en la ruta necesita ser regenerado y redeplomado. Un campo añadido al servicio pero no a la capa delante de él desaparece antes de llegar al llamador, y las pruebas propias del servicio no lo notarán.
Verificar
Comprueba los consumidores reales antes de cambiar una forma — busca en el código de los llamadores en lugar de confiar en la documentación del contrato.
Prueba el contrato en sí mismo: una prueba que afirma la forma serializada detecta un cambio de nombre accidental que una prueba unitaria sobre el controlador omitirá por completo.