01
Qué es y qué problema resuelve
Versionar hace visible que dos consumidores pueden depender de contratos diferentes. Un cambio incompatible exige una transición deliberada: renombrar una propiedad, cambiar su significado o volver obligatorio un campo afecta clientes aunque la base de datos siga funcionando.
02
Ejemplo paso a paso
Punto de partida Endpoints ilustrativos de un catálogo fijo. v2 cambia la estructura y conserva v1 durante la transición; no usa una biblioteca de versionado.
Antes de ejecutar
Requiere un host ASP.NET Core 10 preparado. builder y app corresponden a WebApplication.CreateBuilder y Build; las variables y tipos auxiliares deben definirse. Registra los servicios usados antes de Build. El ZIP de consola no contiene esta API.
app.MapGet("/api/v1/salas/{codigo}", (string codigo) =>
Results.Ok(new { codigo, aforo = 12 }));
app.MapGet("/api/v2/salas/{codigo}", (string codigo) =>
Results.Ok(new { codigo, capacidad = new { personas = 12 } }));Cómo funciona
- Compara los contratos de la versión inicial y la nueva.
- Identifica qué campos o comportamientos cambian para el consumidor.
- Mantén pruebas de ambos contratos durante el período de transición.
Resultado esperado: Un cliente de v1 sigue recibiendo aforo; v2 obtiene capacidad.personas.
03
Cuándo usarlo y qué debes evitar
Usa una estrategia consistente, como versión en la ruta. No prometas compatibilidad solo porque JSON acepta campos adicionales: algunos clientes validan esquemas o enums estrictamente.
Publica fecha y condiciones de retiro, conserva pruebas con consumidores representativos y distingue la versión HTTP de la versión del paquete interno.
Ampliación opcional · contexto y variantes del tema
Contrato HTTP y DTOs explícitos
Un contrato describe entradas, respuestas, errores y permisos. Para crear una reserva acepta sala e intervalo; obtiene el grupo del contexto autenticado. No aceptes un objeto completo Reserva con Cancelada, propietario o auditoría modificables desde el cliente. Usa DTOs de entrada y salida pequeños; el DTO es el límite de confianza del transporte.
POST /api/v1/reservas crea y responde 201 con Location; GET de una reserva devuelve 200 o 404 según la política de visibilidad. 400 expresa entrada mal formada, 401 ausencia de autenticación válida y 403 acceso no autorizado. 409 puede expresar conflicto con estado actual. Un 500 corresponde a un fallo inesperado. Elegir 404 para ocultar recursos ajenos es una política consistente que debes aplicar y probar, no un reemplazo de comprobar permisos.
La ruta v1 es una estrategia de versionado visible. Agregar un campo opcional puede ser compatible; renombrar salaId o cambiar unidades de duración puede romper clientes. Conserva contratos de ejemplo en OpenAPI, acuerda deprecaciones y verifica consumidores. Un DTO compartido entre versiones deja de ser conveniente si ambas necesitan evolucionar de manera diferente.
Punto de partida Estos mensajes usan tipos conocidos por el serializador. El grupo se resuelve después de autenticar; no es un campo que el cliente pueda elegir.
Antes de ejecutar
Tipos completos para el adaptador HTTP
public sealed record CrearReservaDto(
string SalaId,
DateTimeOffset Inicio,
DateTimeOffset Fin);
public sealed record ReservaCreadaDto(Guid Id);Resultado esperado: La entrada no permite asignar un grupo ajeno ni marcar la reserva como aprobada.
04 · Práctica guiada · opcional
Practica lo aprendido
Clasifica agregar un campo opcional, renombrar aforo y cambiar minutos por horas.
- 01Prepara el ejemplo con las dependencias indicadas en «Antes de ejecutar».
- 02Clasifica agregar un campo opcional, renombrar aforo y cambiar minutos por horas.
- 03Comprueba y registra el resultado: Un cliente de v1 sigue recibiendo aforo; v2 obtiene capacidad.personas.
Ver solución orientativa
Evalúa consumidores: renombrar y cambiar unidades son incompatibles. Un campo adicional depende de sus reglas de aceptación.
05
Comprueba lo aprendido
Responde antes de abrir la explicación. Esta comprobación es opcional y no guarda una puntuación.
01¿La versión de EF Core es la versión de tu API?
No. Son contratos distintos con consumidores y políticas de evolución diferentes.
02¿Cómo introducirías capacidad.personas mientras existe un cliente que lee aforo?
Conserva el contrato v1 mientras introduces v2. Prueba ambos con consumidores representativos y acuerda el retiro de v1; renombrar el campo en la misma versión rompe al cliente antiguo.
Cómo demostrar el objetivo
Compara tu práctica con estos resultados. Si solo diseñaste una prueba, registra su resultado como esperado, no como observado.
- El consumidor de v1 conserva aforo y el de v2 recibe capacidad.personas.
- Justificas por qué renombrar o cambiar unidades puede romper un consumidor.
Qué debes recordar
- Versiona el contrato observable.
- Define transición y retiro con evidencia de compatibilidad.
Tu cuaderno · notas personales
Cuaderno local
Tus notas del contenido
Se guardan únicamente en este dispositivo. Puedes exportarlas cuando quieras.
Material de apoyo · descarga, glosario y referencias
Explicaciones, ejemplos y prácticas propios de Academia de Software. Los fragmentos de integración requieren las dependencias indicadas; el ZIP contiene el núcleo de consola. Las lecturas externas se consultan en su sitio original y conservan sus condiciones. Procedencia y condiciones de uso.