APIs que sobreviven al cambio
Haz evolucionar una interfaz pública mientras clientes, trabajos y despliegues avanzan a velocidades distintas.
AL TERMINAR, PODRÁS
- Reconocer cambios incompatibles con versiones anteriores
- Definir el alcance de la idempotencia y el comportamiento ante conflictos
- Diseñar a propósito la paginación y la evolución del esquema
Descripción del diagrama: Cliente antiguo → POST /jobs; Cliente nuevo → POST /jobs; POST /jobs → Trabajos; Idempotency-Key → POST /jobs
Tus clientes despliegan a su propio ritmo
Una API es una promesa hecha a clientes que quizá no puedas actualizar al mismo tiempo.
Quitar un campo, cambiar su tipo o darle un significado nuevo puede romper a esos clientes. Incluso agregar un valor a un enum puede romper a quienes suponen que el conjunto es completo. Prefiere reglas de compatibilidad explícitas, valores por defecto documentados y un periodo de deprecación (aviso de retiro) cuando un cambio incompatible sea necesario.
En el trabajo encolado, recuerda que los trabajos guardados pueden usar una forma antigua mucho después de que el código que los creó haya sido reemplazado.
Dale sentido a las peticiones repetidas
Una clave de idempotencia permite que un cliente identifique los reintentos de una misma operación.
Limítala al inquilino (tenant) o cliente adecuado y guarda de forma duradera la relación entre la clave, el significado de la petición y el resultado. Reusar la misma clave con un cuerpo distinto debe tener un comportamiento de conflicto definido. Los envíos concurrentes con una misma clave necesitan una regla de unicidad que haga cumplir la base de datos.
Documenta cuánto tiempo se conservan los registros; después de que expiren, un reintento puede tratarse como nuevo. La clave es un protocolo, no una cabecera mágica que hace que todos los efectos posteriores ocurran una sola vez.
Diseña para colecciones que se mueven
La paginación por desplazamiento (offset) es simple, pero puede saltarse o repetir registros cuando las inserciones y los borrados mueven posiciones entre peticiones.
La paginación por cursor usa un orden estable y un límite de continuación, a menudo con un desempate único. Aun así necesita expectativas de consistencia documentadas cuando los datos cambian. Pon un tope al tamaño de página y evita exponer detalles internos innecesarios en los cursores.
Para cambios de esquema, despliega lectores y escritores compatibles por etapas: agrega un campo, soporta ambas formas, rellena los datos donde haga falta (backfill) y elimina el comportamiento antiguo solo cuando los consumidores se hayan movido.
ERROR FRECUENTE
Una caché de idempotencia sin unicidad duradera ni comprobación del cuerpo puede crear duplicados bajo concurrencia o reutilizar en silencio el resultado equivocado.
INTÉNTALO TÚ
Define qué devuelve Relay cuando la misma clave de idempotencia llega dos veces con el mismo cuerpo, y luego con un cuerpo distinto. Incluye la retención y las peticiones concurrentes.
Decide en el laboratorio.
El checkpoint de dos preguntas, tus notas y tu progreso guardado están en el laboratorio. Gratis y sin cuenta.
Abrir en el laboratorio ↗CONÉCTALO CON RELAY
Agrega a Relay un cuerpo de trabajo con versión y escribe un plan de compatibilidad para introducir un concepto obligatorio nuevo sin romper de inmediato los trabajos antiguos.