Análisis de contrato · Bloque 1
EX-B1-09
Cambio compatible o ruptura
Un proveedor propone una versión nueva de su contrato y afirma que ningún consumidor deberá cambiar. Debes revisar el diff antes de aprobarlo.
Cómo abordarla
Decide sin fingir que el análisis es implementación
Responde primero con la evidencia disponible. Consulta la teoría solo para comprobar el supuesto que no puedas justificar.
Abrir análisis técnico
1. Abre la evidencia
- OpenAPI v1.0Documento OpenAPI 3.1 completo del contrato vigente.
- OpenAPI v1.1 propuestoDocumento OpenAPI 3.1 completo del contrato propuesto.
- Diff OpenAPIDiff unificado entre ambos documentos, con claves OAS reales.
- Informe de compatibilidadPlantilla para impacto, consumidor afectado y transición.
2. Analiza y decide
- Clasifica cada cambio como compatible, potencialmente incompatible o ruptura clara.
- Identifica qué tipo de consumidor puede resultar afectado y por qué.
- Separa cambios de documentación de cambios en comportamiento observable.
- Propón una transición proporcional para cada ruptura confirmada.
- Ordena los hallazgos por impacto y confianza.
3. Entrega una decisión revisable
- Informe de compatibilidad línea por línea.
- Resumen ejecutivo con riesgos y transición recomendada.
Registra tu decisión antes de contrastarla con el material.
Pregunta central
¿Qué cambios puede aceptar un consumidor existente sin modificarse y cuáles rompen peticiones o respuestas que antes eran válidas?
Diff OpenAPI
--- ex-b1-09-openapi-v1.yaml
+++ ex-b1-09-openapi-v1.1.yaml
@@ -1,29 +1,30 @@
openapi: 3.1.0
info:
title: Records API
- version: 1.0.0
+ version: 1.1.0
paths:
- /records/{record_id}:
+ /record/{id}:
get:
summary: Get a record
- description: Returns one record.
+ description: Returns one record. Rate limiting may apply.
operationId: getRecord
parameters:
- - name: record_id
+ - name: id
in: path
required: true
schema:
- type: integer
- minimum: 1
+ type: string
responses:
"200":
- description: Record found
+ description: Record found or absent
content:
application/json:
schema:
- $ref: "#/components/schemas/Record"
- "404":
- description: Record not found
+ oneOf:
+ - $ref: "#/components/schemas/Record"
+ - type: "null"
+ "429":
+ description: Too many requests
content:
application/json:
schema:
$ref: "#/components/schemas/Problem"
@@ -32,12 +33,17 @@ components:
schemas:
Record:
type: object
- required: [id, title]
+ required: [id, title, owner_id]
properties:
id:
- type: integer
+ type: string
title:
type: string
+ owner_id:
+ type: string
+ archived_at:
+ type: [string, "null"]
+ format: date-time
Problem:
type: object
required: [code, message]Para ordenar tu razonamiento
- Clasifica cada cambio como compatible, dudoso o ruptura.
- Explica qué consumidor se vería afectado en los dos cambios de mayor impacto.
- Propón una transición breve para una ruptura confirmada.
Escribe lo que piensas. Se guarda automáticamente en este navegador.
Sin respuesta guardada.
Pistas opcionales
Pista única · Piensa como un consumidor existente
- Imagina una petición válida ayer y una respuesta que el cliente sabía interpretar ayer. Comprueba ambas contra el contrato propuesto.
Profundización opcional
Identificar cambios compatibles y rupturas en rutas, nombres, tipos, campos requeridos y respuestas.
Contexto adicional
- Considera clientes que generan código desde OpenAPI y clientes que interpretan respuestas manualmente.
- No todo cambio visible rompe necesariamente el contrato; explica quién podría verse afectado.
Cómo revisar tu respuesta
- Se revisan rutas, parámetros, tipos, required y códigos de respuesta.
- Añadir información opcional no se trata igual que exigir un campo nuevo.
- El impacto se relaciona con consumidores concretos.
- Las transiciones evitan mantener versiones paralelas sin necesidad demostrada.
Evidencia, revisión y reinicio
- Revisión razonada guardada localmente en el navegador.
- Informe de compatibilidad y transición si se utiliza la plantilla opcional.
Revisión: con Codex, utilizando la evidencia y los criterios anteriores; no se publica una solución oficial.
Reinicio: Borrar la respuesta desde la tarjeta y volver a descargar el diff y el informe vacíos.