Práctica extendida · Bloque 1
EX-B1-S01
Soporte de una API desconocida
Una aplicación móvil dejó de crear expedientes tras una actualización del proveedor. El mismo ticket, tráfico capturado y documento OpenAPI acotado se conservan durante las tres partes.
Cómo abordarla
Aplicación progresiva sobre una base ejecutable
Mantén el mismo workspace entre partes y cierra cada checkpoint con código ejecutable, pruebas y una respuesta HTTP o traza.
Abrir práctica extendida: base común y 3 partes
Base común
- El cliente informa de que la red funciona y otras operaciones contra el mismo host responden.
- El ZIP contiene una API FastAPI, un cliente local y una suite que reproduce el incidente.
- El contrato declara un media type específico para la creación y el starter diverge de él.
- Cada parte termina con código ejecutable, una prueba negativa y una respuesta HTTP capturada.
Paquete de trabajo
- Workspace ejecutable de soporteAPI, cliente, OpenAPI, tests y checkpoints vacíos para las tres partes.
- Ticket y tráfico capturadoIncidente, petición, respuesta y contexto operativo.
- Documento OpenAPI acotadoDocumento OpenAPI 3.1 que describe la creación de expedientes.
- Cuaderno de la serieCheckpoint vacío para conservar evidencias, hipótesis y decisiones entre partes.
Entorno, evidencia y reinicio
Entorno: Paquete descargable trabajado en un directorio separado del repositorio.
- API y cliente local ejecutados en cada checkpoint.
- Tests de reproducción, reparación y compatibilidad escritos por el alumno.
Revisión: con Codex, utilizando los artefactos y criterios de cada parte; no se publica una solución oficial.
Reinicio: Eliminar el workspace y volver a extraer el ZIP; cada parte incluye un commit o copia de checkpoint.
Parte 1 · Apoyo alto
EX-B1-S01-01 · Preparar la reproducción mínima
Arrancar la API, convertir el tráfico capturado en un test de regresión y reproducir el fallo sin corregirlo todavía.
Qué debes hacer
- Instala el starter, ejecuta pytest y arranca la API sin modificar `app.py`.
- Escribe un test que materialice método, path, media type y body del tráfico capturado y espere el 415 observado.
- Reproduce el mismo intercambio con un comando `curl` y correlaciónalo con el log mediante request ID.
- Guarda el estado como checkpoint; todavía no cambies el comportamiento.
Entrega esperada
- Test de reproducción y comando curl ejecutables.
- Salida 415 y log correlacionado con request ID.
Criterios de aceptación
- El comando reproduce `POST /v2/cases` con `application/json` y el JSON capturado.
- La salida esperada del comando sigue siendo `415`; no se adelanta la solución.
- `mob-91c7` vincula request y response y no se inventan credenciales.
Evidencia para revisión
- Test de regresión que reproduce el 415 sin editar la API.
- Comando curl y respuesta correlacionada con el log local.
Reinicio de esta parte: Reiniciar desde una copia nueva del paquete y conservar el resultado como checkpoint independiente.
Pista 1 · Reproduce antes de corregir
- El comando debe representar lo que hizo el cliente, aunque ya veas una posible corrección.
Pista 2 · Conserva lo necesario
- Método, URL, media types y body bastan para esta reproducción; el token redactado no es reutilizable.
Parte 2 · Apoyo moderado
EX-B1-S01-02 · Clasificar el fallo
Localizar la divergencia entre OpenAPI, cliente y endpoint y reparar la frontera mínima sin cambiar el dominio.
Qué debes hacer
- Añade tests discriminantes para transporte, parsing JSON y media type antes de editar la API.
- Localiza la primera divergencia entre OpenAPI, cliente y código y aplica el cambio mínimo defendible.
- Mantén verde el test de reproducción histórica y añade el comportamiento corregido como caso separado.
- Ejecuta toda la suite y documenta dos hipótesis descartadas por sus resultados.
Entrega esperada
- Parche mínimo y matriz test → hipótesis → resultado.
- Salida de pytest antes/después y dos descartes razonados.
Criterios de aceptación
- El diagnóstico diferencia que HTTP haya respondido de que la operación haya sido aceptada.
- La validez sintáctica del JSON se evalúa aparte de su conformidad contractual.
- Los descartes utilizan evidencia y no intuiciones sobre frameworks.
Evidencia para revisión
- Parche mínimo en la frontera HTTP y tests antes/después.
- Dos hipótesis descartadas mediante ejecución controlada.
Reinicio de esta parte: Volver al checkpoint de la parte 1 o reconstruirlo desde una copia limpia del paquete.
Pista · Compara observado y prometido
- Busca la primera diferencia verificable entre el mensaje capturado y la operación descrita en OpenAPI.
Parte 3 · Apoyo ligero
EX-B1-S01-03 · Proponer el contrato corregido
Cerrar la reparación en código: alinear implementación, OpenAPI y cliente y demostrar una transición compatible.
Qué debes hacer
- Implementa el contrato final en el endpoint y configura su documentación OpenAPI sin editar el YAML fuente para ocultar la divergencia.
- Corrige el cliente local y añade una prueba que cree un caso y otra que rechace media type no permitido.
- Compara paths, request body y responses del OpenAPI generado con el contrato fuente.
- Define y prueba una transición para el consumidor anterior; registra qué compatibilidad conservas y hasta dónde.
Entrega esperada
- API, cliente y suite final ejecutables.
- Diff de OpenAPI y nota breve de compatibilidad.
- Respuesta 201 y rechazo contractual capturados.
Criterios de aceptación
- La propuesta corrige la discrepancia diagnosticada.
- La transición identifica al consumidor afectado.
- Los criterios pueden comprobarse mediante mensajes HTTP.
Evidencia para revisión
- OpenAPI generado y respuestas reales alineadas.
- Regresión de compatibilidad y decisión de transición.
Reinicio de esta parte: Volver al checkpoint de la parte 2 y trabajar sobre una copia nueva del documento OpenAPI acotado.
Pista · Cambia lo mínimo necesario
- No rediseñes toda la API si una frontera concreta explica el incidente.