Práctica · Bloque 2
Practica el contrato de tu primera API
Diagnostica, diseña e implementa la frontera HTTP de una aplicación pequeña. Las respuestas breves se guardan localmente bajo la misma clave estable del bloque 1; los laboratorios se realizan en un workspace temporal fuera de este repositorio.
Cómo trabajar este bloque
Parte siempre de evidencia: reproduce, formula una hipótesis, cambia una sola frontera y verifica status, headers, body y OpenAPI.
Los ejercicios de apoyo preparan el mecanismo. El checkpoint cambia el caso y se intenta sin volver a abrir las pistas anteriores; así puedes distinguir práctica asistida de una comprobación independiente.
Descarga los starters en un directorio temporal fuera de este repositorio. No contienen solución ni pruebas que revelen la respuesta.
Paso 1 · Unidad 2.1
Pon en marcha y diagnostica la ruta
Evidencia del paso: La aplicación importa, la ruta correcta responde y puedes explicar el orden de coincidencia.
Antes de ejecutar: Antes de ejecutar, predice método, ruta, status, body y dónde debería aparecer la operación en OpenAPI.
Práctica guiada y focalizada
EX-B2-01
La aplicación que Uvicorn no puede importar
Un compañero ejecuta `uv run uvicorn app.main:app --reload`, pero el proceso termina antes de abrir el puerto.
Pensar y responder en la web
Predice y guarda aquí tu razonamiento antes de abrir el material; después contrástalo en el workspace.
Pregunta central
¿Qué significa cada segmento de `app.main:app`, dónde falla el arranque y qué comprobación mínima demuestra la reparación?
Información que necesitas
Traceback inicial: ModuleNotFoundError: No module named 'app.main'; el árbol descargado contiene src/records_api/main.py.Para ordenar tu razonamiento
- ¿Qué comportamiento observas y qué parte es todavía una hipótesis?
- ¿Cuál es el cambio mínimo que permite verificar la causa o el contrato?
- ¿Qué evidencia conservarías para demostrar que no rompiste otra frontera?
Trabajo en el workspace
- Reproduce el fallo desde el directorio indicado.
- Comprueba la importación con Python antes de abrir el servidor.
- Corrige entrypoint, estructura o directorio sin mover archivos innecesariamente.
- Demuestra `GET /health` y documenta la causa raíz.
Entrega esperada
- Implementación o propuesta mínima.
- Evidencia reproducible del caso principal y, al menos, un caso inválido.
- Nota breve con la decisión tomada y la alternativa descartada.
Escribe lo que piensas. Se guarda automáticamente en este navegador.
Sin respuesta guardada.
Pistas opcionales
Pista 1 · Localiza la frontera
- Separa importación, enrutado, extracción, validación, operación y serialización.
- Lee el status, los headers y la ubicación del error antes de editar.
Pista 2 · Reduce la prueba
- Usa una petición válida y una inválida que difieran en una sola variable.
- Compara el comportamiento con `/openapi.json` cuando el contrato esté documentado.
Profundización opcional
Distinguir directorio de trabajo, módulo importable y atributo ASGI, y reparar solo la causa demostrada.
Contexto adicional
- Trabaja únicamente dentro del alcance del bloque: una aplicación pequeña y estado en memoria.
- No hay solución oficial publicada; el material contiene huecos y defectos deliberados.
- Justifica las decisiones por el mensaje HTTP y el contrato observable, no solo porque el código arranque.
Cómo revisar tu respuesta
- La explicación diferencia módulo y atributo.
- La importación directa y el servidor arrancan desde un checkout limpio.
- No se oculta el problema alterando PYTHONPATH global.
Evidencia, revisión y reinicio
- Decisión razonada guardada localmente en la web.
- Código o informe ejecutable en el workspace temporal, más una captura de curl/OpenAPI cuando proceda.
Revisión: con Codex, utilizando la evidencia y los criterios anteriores; no se publica una solución oficial.
Reinicio: Eliminar el workspace temporal y volver a descargar el material inicial; no hay estado persistente externo.
Material descargable opcional
- Proyecto con importación defectuosaStarter autocontenido con árbol, traceback y aplicación mínima desplazada.
Teoría que puedes consultar
EX-B2-02
«me» no es un identificador
`GET /records/me` entra en `/records/{record_id}` y devuelve el registro cuyo id literal es «me».
Pensar y responder en la web
Predice y guarda aquí tu razonamiento antes de abrir el material; después contrástalo en el workspace.
Pregunta central
¿Por qué coincide la operación equivocada y qué orden mantiene ambas rutas observables?
Para ordenar tu razonamiento
- ¿Qué comportamiento observas y qué parte es todavía una hipótesis?
- ¿Cuál es el cambio mínimo que permite verificar la causa o el contrato?
- ¿Qué evidencia conservarías para demostrar que no rompiste otra frontera?
Trabajo en el workspace
- Predice el resultado de tres URLs antes de ejecutar.
- Reproduce el sombreado con curl.
- Cambia únicamente el orden de registro y repite las tres pruebas.
- Compara el documento OpenAPI antes y después.
Entrega esperada
- Implementación o propuesta mínima.
- Evidencia reproducible del caso principal y, al menos, un caso inválido.
- Nota breve con la decisión tomada y la alternativa descartada.
Escribe lo que piensas. Se guarda automáticamente en este navegador.
Sin respuesta guardada.
Pistas opcionales
Pista 1 · Localiza la frontera
- Separa importación, enrutado, extracción, validación, operación y serialización.
- Lee el status, los headers y la ubicación del error antes de editar.
Pista 2 · Reduce la prueba
- Usa una petición válida y una inválida que difieran en una sola variable.
- Compara el comportamiento con `/openapi.json` cuando el contrato esté documentado.
Profundización opcional
Explicar y corregir el sombreado entre una ruta estática y otra dinámica.
Contexto adicional
- Trabaja únicamente dentro del alcance del bloque: una aplicación pequeña y estado en memoria.
- No hay solución oficial publicada; el material contiene huecos y defectos deliberados.
- Justifica las decisiones por el mensaje HTTP y el contrato observable, no solo porque el código arranque.
Cómo revisar tu respuesta
- `/me` llega a la ruta estática.
- Un id normal sigue llegando a la ruta dinámica.
- La explicación no atribuye el fallo al nombre de la función.
Evidencia, revisión y reinicio
- Decisión razonada guardada localmente en la web.
- Código o informe ejecutable en el workspace temporal, más una captura de curl/OpenAPI cuando proceda.
Revisión: con Codex, utilizando la evidencia y los criterios anteriores; no se publica una solución oficial.
Reinicio: Eliminar el workspace temporal y volver a descargar el material inicial; no hay estado persistente externo.
Material descargable opcional
- Aplicación con rutas sombreadasMódulo mínimo con orden defectuoso y matriz de peticiones.
Teoría que puedes consultar
Transferencia: Explica qué evidencia distinguiría un fallo de importación, un 404 y un 405 en otra aplicación.
Paso 2 · Unidad 2.2
Coloca cada dato donde expresa mejor su intención
Evidencia del paso: Distingues path, query, header, cookie, body, formulario y archivo, incluida la ausencia frente a null.
Antes de ejecutar: Clasifica identificador, filtro, correlación y representación antes de mirar una firma FastAPI.
Práctica guiada y focalizada
EX-B2-03
¿Path, query, header o body?
Un requisito mezcla identificador, paginación, correlación, modo de simulación y datos de creación sin decidir su lugar en HTTP.
Pensar y responder en la web
Predice y guarda aquí tu razonamiento antes de abrir el material; después contrástalo en el workspace.
Pregunta central
¿Dónde debe viajar cada dato y qué decisión de significado respalda esa elección?
Para ordenar tu razonamiento
- ¿Qué comportamiento observas y qué parte es todavía una hipótesis?
- ¿Cuál es el cambio mínimo que permite verificar la causa o el contrato?
- ¿Qué evidencia conservarías para demostrar que no rompiste otra frontera?
Trabajo en el workspace
- Completa la matriz de fuentes y obligatoriedad.
- Escribe una firma FastAPI sin implementar lógica de negocio.
- Comprueba el esquema generado y una petición inválida por fuente.
Entrega esperada
- Implementación o propuesta mínima.
- Evidencia reproducible del caso principal y, al menos, un caso inválido.
- Nota breve con la decisión tomada y la alternativa descartada.
Escribe lo que piensas. Se guarda automáticamente en este navegador.
Sin respuesta guardada.
Pistas opcionales
Pista 1 · Localiza la frontera
- Separa importación, enrutado, extracción, validación, operación y serialización.
- Lee el status, los headers y la ubicación del error antes de editar.
Pista 2 · Reduce la prueba
- Usa una petición válida y una inválida que difieran en una sola variable.
- Compara el comportamiento con `/openapi.json` cuando el contrato esté documentado.
Profundización opcional
Asignar una fuente a cada dato y expresar obligatoriedad y tipo con `Annotated`.
Contexto adicional
- Trabaja únicamente dentro del alcance del bloque: una aplicación pequeña y estado en memoria.
- No hay solución oficial publicada; el material contiene huecos y defectos deliberados.
- Justifica las decisiones por el mensaje HTTP y el contrato observable, no solo porque el código arranque.
Cómo revisar tu respuesta
- Identidad, filtros, metadatos y representación no se mezclan.
- Los defaults reflejan obligatoriedad real.
- OpenAPI coincide con la matriz.
Evidencia, revisión y reinicio
- Decisión razonada guardada localmente en la web.
- Código o informe ejecutable en el workspace temporal, más una captura de curl/OpenAPI cuando proceda.
Revisión: con Codex, utilizando la evidencia y los criterios anteriores; no se publica una solución oficial.
Reinicio: Eliminar el workspace temporal y volver a descargar el material inicial; no hay estado persistente externo.
Material descargable opcional
- Requisitos sin clasificarHistorias, diccionario de campos y ejemplo HTTP para implementar la frontera.
Teoría que puedes consultar
EX-B2-04
Correlación en header, preferencia en cookie
Soporte necesita rastrear cada petición y la interfaz recuerda un modo de visualización no sensible.
Pensar y responder en la web
Predice y guarda aquí tu razonamiento antes de abrir el material; después contrástalo en el workspace.
Pregunta central
¿Qué validaciones mínimas evitan aceptar una correlación vacía y una preferencia fuera del vocabulario?
Para ordenar tu razonamiento
- ¿Qué comportamiento observas y qué parte es todavía una hipótesis?
- ¿Cuál es el cambio mínimo que permite verificar la causa o el contrato?
- ¿Qué evidencia conservarías para demostrar que no rompiste otra frontera?
Trabajo en el workspace
- Implementa `X-Correlation-ID` requerido y `display_mode` opcional.
- Prueba header ausente, cookie ausente y cookie inválida.
- Verifica nombres públicos en OpenAPI y que no se registre ningún valor sensible.
Entrega esperada
- Implementación o propuesta mínima.
- Evidencia reproducible del caso principal y, al menos, un caso inválido.
- Nota breve con la decisión tomada y la alternativa descartada.
Escribe lo que piensas. Se guarda automáticamente en este navegador.
Sin respuesta guardada.
Pistas opcionales
Pista 1 · Localiza la frontera
- Separa importación, enrutado, extracción, validación, operación y serialización.
- Lee el status, los headers y la ubicación del error antes de editar.
Pista 2 · Reduce la prueba
- Usa una petición válida y una inválida que difieran en una sola variable.
- Compara el comportamiento con `/openapi.json` cuando el contrato esté documentado.
Profundización opcional
Declarar un header con alias explícito y una cookie opcional sin convertirlos en parámetros de negocio.
Contexto adicional
- Trabaja únicamente dentro del alcance del bloque: una aplicación pequeña y estado en memoria.
- No hay solución oficial publicada; el material contiene huecos y defectos deliberados.
- Justifica las decisiones por el mensaje HTTP y el contrato observable, no solo porque el código arranque.
Cómo revisar tu respuesta
- El header requerido genera una ubicación de error útil.
- La ausencia de cookie conserva el default.
- El contrato no usa cookies para autenticación.
Evidencia, revisión y reinicio
- Decisión razonada guardada localmente en la web.
- Código o informe ejecutable en el workspace temporal, más una captura de curl/OpenAPI cuando proceda.
Revisión: con Codex, utilizando la evidencia y los criterios anteriores; no se publica una solución oficial.
Reinicio: Eliminar el workspace temporal y volver a descargar el material inicial; no hay estado persistente externo.
Material descargable opcional
- Starter de correlaciónAplicación parcial con casos HTTP descritos como comentarios.
Teoría que puedes consultar
EX-B2-05
JSON, formulario o archivo
Tres historias de usuario requieren crear un expediente, iniciar sesión mediante formulario y adjuntar un PDF con metadatos.
Pensar y responder en la web
Predice y guarda aquí tu razonamiento antes de abrir el material; después contrástalo en el workspace.
Pregunta central
¿Qué formato corresponde a cada historia y por qué no existe un body JSON separado junto a un archivo multipart?
Para ordenar tu razonamiento
- ¿Qué comportamiento observas y qué parte es todavía una hipótesis?
- ¿Cuál es el cambio mínimo que permite verificar la causa o el contrato?
- ¿Qué evidencia conservarías para demostrar que no rompiste otra frontera?
Trabajo en el workspace
- Clasifica las tres historias y dibuja el mensaje HTTP.
- Escribe firmas mínimas con `Body`, `Form`, `File` o `UploadFile` según proceda.
- Demuestra content types correctos y un caso rechazado.
Entrega esperada
- Implementación o propuesta mínima.
- Evidencia reproducible del caso principal y, al menos, un caso inválido.
- Nota breve con la decisión tomada y la alternativa descartada.
Escribe lo que piensas. Se guarda automáticamente en este navegador.
Sin respuesta guardada.
Pistas opcionales
Pista 1 · Localiza la frontera
- Separa importación, enrutado, extracción, validación, operación y serialización.
- Lee el status, los headers y la ubicación del error antes de editar.
Pista 2 · Reduce la prueba
- Usa una petición válida y una inválida que difieran en una sola variable.
- Compara el comportamiento con `/openapi.json` cuando el contrato esté documentado.
Profundización opcional
Elegir media type y primitivas FastAPI adecuadas para JSON, form-urlencoded y multipart.
Contexto adicional
- Trabaja únicamente dentro del alcance del bloque: una aplicación pequeña y estado en memoria.
- No hay solución oficial publicada; el material contiene huecos y defectos deliberados.
- Justifica las decisiones por el mensaje HTTP y el contrato observable, no solo porque el código arranque.
Cómo revisar tu respuesta
- El archivo usa multipart y `UploadFile`.
- La creación estructurada normal usa JSON.
- No se promete JSON y multipart como dos cuerpos simultáneos.
Evidencia, revisión y reinicio
- Decisión razonada guardada localmente en la web.
- Código o informe ejecutable en el workspace temporal, más una captura de curl/OpenAPI cuando proceda.
Revisión: con Codex, utilizando la evidencia y los criterios anteriores; no se publica una solución oficial.
Reinicio: Eliminar el workspace temporal y volver a descargar el material inicial; no hay estado persistente externo.
Material descargable opcional
- Historias de transporteTres requisitos y ejemplos de clientes incompletos.
Teoría que puedes consultar
EX-B2-06
Ausente no significa null
Un PATCH borra el título cuando el cliente no lo envía porque el código solo mira el valor final `None`.
Pensar y responder en la web
Predice y guarda aquí tu razonamiento antes de abrir el material; después contrástalo en el workspace.
Pregunta central
¿Qué resultado debe producir `{}`, `{"title": null}` y `{"title": "Nueva"}`?
Para ordenar tu razonamiento
- ¿Qué comportamiento observas y qué parte es todavía una hipótesis?
- ¿Cuál es el cambio mínimo que permite verificar la causa o el contrato?
- ¿Qué evidencia conservarías para demostrar que no rompiste otra frontera?
Trabajo en el workspace
- Predice `model_fields_set` para los tres payloads.
- Implementa un patch en memoria que aplique solo campos presentes.
- Decide si `null` está permitido y haz que el contrato lo refleje.
Entrega esperada
- Implementación o propuesta mínima.
- Evidencia reproducible del caso principal y, al menos, un caso inválido.
- Nota breve con la decisión tomada y la alternativa descartada.
Escribe lo que piensas. Se guarda automáticamente en este navegador.
Sin respuesta guardada.
Pistas opcionales
Pista 1 · Localiza la frontera
- Separa importación, enrutado, extracción, validación, operación y serialización.
- Lee el status, los headers y la ubicación del error antes de editar.
Pista 2 · Reduce la prueba
- Usa una petición válida y una inválida que difieran en una sola variable.
- Compara el comportamiento con `/openapi.json` cuando el contrato esté documentado.
Profundización opcional
Distinguir campo omitido, `null` explícito y default mediante presencia y `exclude_unset`.
Contexto adicional
- Trabaja únicamente dentro del alcance del bloque: una aplicación pequeña y estado en memoria.
- No hay solución oficial publicada; el material contiene huecos y defectos deliberados.
- Justifica las decisiones por el mensaje HTTP y el contrato observable, no solo porque el código arranque.
Cómo revisar tu respuesta
- Omitir no modifica el recurso.
- `null` se acepta o rechaza explícitamente.
- No se confía solo en comparar con `None`.
Evidencia, revisión y reinicio
- Decisión razonada guardada localmente en la web.
- Código o informe ejecutable en el workspace temporal, más una captura de curl/OpenAPI cuando proceda.
Revisión: con Codex, utilizando la evidencia y los criterios anteriores; no se publica una solución oficial.
Reinicio: Eliminar el workspace temporal y volver a descargar el material inicial; no hay estado persistente externo.
Material descargable opcional
- Matriz absent/null/defaultCasos sintéticos y estado inicial para una actualización parcial.
Teoría que puedes consultar
Transferencia: Ante un requisito nuevo, justificas la fuente HTTP y la semántica de ausencia antes de escribir código.
Paso 3 · Unidad 2.3
Haz explícitas las reglas del modelo
Evidencia del paso: El modelo acepta, normaliza o rechaza con reglas localizables y separa entrada, actualización y salida.
Antes de ejecutar: Predice qué reglas dependen de un campo, de varios campos o de quién puede enviar cada dato.
Práctica guiada y focalizada
EX-B2-07
Field, field_validator o model_validator
Un modelo concentra patrón, normalización, fechas cruzadas y duplicados en un único `model_validator`.
Pensar y responder en la web
Predice y guarda aquí tu razonamiento antes de abrir el material; después contrástalo en el workspace.
Pregunta central
¿Qué regla pertenece a cada mecanismo y cuál no pertenece a Pydantic?
Para ordenar tu razonamiento
- ¿Qué comportamiento observas y qué parte es todavía una hipótesis?
- ¿Cuál es el cambio mínimo que permite verificar la causa o el contrato?
- ¿Qué evidencia conservarías para demostrar que no rompiste otra frontera?
Trabajo en el workspace
- Clasifica seis reglas antes de editar.
- Refactoriza restricciones declarativas, normalización y comparación cruzada.
- Extrae la comprobación de duplicados de los validadores.
Entrega esperada
- Implementación o propuesta mínima.
- Evidencia reproducible del caso principal y, al menos, un caso inválido.
- Nota breve con la decisión tomada y la alternativa descartada.
Escribe lo que piensas. Se guarda automáticamente en este navegador.
Sin respuesta guardada.
Pistas opcionales
Pista 1 · Localiza la frontera
- Separa importación, enrutado, extracción, validación, operación y serialización.
- Lee el status, los headers y la ubicación del error antes de editar.
Pista 2 · Reduce la prueba
- Usa una petición válida y una inválida que difieran en una sola variable.
- Compara el comportamiento con `/openapi.json` cuando el contrato esté documentado.
Profundización opcional
Mover cada regla a la frontera más estrecha y dejar fuera el estado externo.
Contexto adicional
- Trabaja únicamente dentro del alcance del bloque: una aplicación pequeña y estado en memoria.
- No hay solución oficial publicada; el material contiene huecos y defectos deliberados.
- Justifica las decisiones por el mensaje HTTP y el contrato observable, no solo porque el código arranque.
Cómo revisar tu respuesta
- Los rangos simples usan `Field`.
- La relación entre fechas usa `model_validator` y devuelve `self`.
- Ningún validador consulta estado externo.
Evidencia, revisión y reinicio
- Decisión razonada guardada localmente en la web.
- Código o informe ejecutable en el workspace temporal, más una captura de curl/OpenAPI cuando proceda.
Revisión: con Codex, utilizando la evidencia y los criterios anteriores; no se publica una solución oficial.
Reinicio: Eliminar el workspace temporal y volver a descargar el material inicial; no hay estado persistente externo.
Material descargable opcional
- Modelo con validación concentradaCódigo parcial con reglas deliberadamente mal ubicadas.
Teoría que puedes consultar
EX-B2-08
Expediente anidado y vocabulario cerrado
Los payloads mezclan datos del responsable, estado libre y documentos sin estructura, lo que produce errores difíciles de localizar.
Pensar y responder en la web
Predice y guarda aquí tu razonamiento antes de abrir el material; después contrástalo en el workspace.
Pregunta central
¿Qué submodelos representan conceptos reutilizables y qué vocabularios deben cerrarse?
Para ordenar tu razonamiento
- ¿Qué comportamiento observas y qué parte es todavía una hipótesis?
- ¿Cuál es el cambio mínimo que permite verificar la causa o el contrato?
- ¿Qué evidencia conservarías para demostrar que no rompiste otra frontera?
Trabajo en el workspace
- Modela responsable, periodo, documento y expediente.
- Usa enum para estado y `default_factory` para colecciones.
- Valida las muestras y compara las rutas de error.
Entrega esperada
- Implementación o propuesta mínima.
- Evidencia reproducible del caso principal y, al menos, un caso inválido.
- Nota breve con la decisión tomada y la alternativa descartada.
Escribe lo que piensas. Se guarda automáticamente en este navegador.
Sin respuesta guardada.
Pistas opcionales
Pista 1 · Localiza la frontera
- Separa importación, enrutado, extracción, validación, operación y serialización.
- Lee el status, los headers y la ubicación del error antes de editar.
Pista 2 · Reduce la prueba
- Usa una petición válida y una inválida que difieran en una sola variable.
- Compara el comportamiento con `/openapi.json` cuando el contrato esté documentado.
Profundización opcional
Construir modelos anidados, enums y colecciones acotadas con errores localizables.
Contexto adicional
- Trabaja únicamente dentro del alcance del bloque: una aplicación pequeña y estado en memoria.
- No hay solución oficial publicada; el material contiene huecos y defectos deliberados.
- Justifica las decisiones por el mensaje HTTP y el contrato observable, no solo porque el código arranque.
Cómo revisar tu respuesta
- Las estructuras anidadas aparecen en OpenAPI.
- Un enum inválido identifica el campo exacto.
- Los defaults mutables usan factoría.
Evidencia, revisión y reinicio
- Decisión razonada guardada localmente en la web.
- Código o informe ejecutable en el workspace temporal, más una captura de curl/OpenAPI cuando proceda.
Revisión: con Codex, utilizando la evidencia y los criterios anteriores; no se publica una solución oficial.
Reinicio: Eliminar el workspace temporal y volver a descargar el material inicial; no hay estado persistente externo.
Material descargable opcional
- Muestras de expedientesPayloads sintéticos válidos e inválidos sin respuesta marcada.
Teoría que puedes consultar
EX-B2-09
Un modelo no sirve para todo
La API usa `Record` para crear, actualizar y responder: el cliente puede enviar `id` y la salida publica `internal_note`.
Pensar y responder en la web
Predice y guarda aquí tu razonamiento antes de abrir el material; después contrástalo en el workspace.
Pregunta central
¿Qué campos controla el cliente en cada operación y qué campos son exclusivamente públicos o internos?
Para ordenar tu razonamiento
- ¿Qué comportamiento observas y qué parte es todavía una hipótesis?
- ¿Cuál es el cambio mínimo que permite verificar la causa o el contrato?
- ¿Qué evidencia conservarías para demostrar que no rompiste otra frontera?
Trabajo en el workspace
- Construye una matriz de propiedad por operación.
- Define `RecordCreate`, `RecordUpdate` y `RecordPublic`.
- Conecta las operaciones y demuestra filtrado y patch parcial.
Entrega esperada
- Implementación o propuesta mínima.
- Evidencia reproducible del caso principal y, al menos, un caso inválido.
- Nota breve con la decisión tomada y la alternativa descartada.
Escribe lo que piensas. Se guarda automáticamente en este navegador.
Sin respuesta guardada.
Pistas opcionales
Pista 1 · Localiza la frontera
- Separa importación, enrutado, extracción, validación, operación y serialización.
- Lee el status, los headers y la ubicación del error antes de editar.
Pista 2 · Reduce la prueba
- Usa una petición válida y una inválida que difieran en una sola variable.
- Compara el comportamiento con `/openapi.json` cuando el contrato esté documentado.
Profundización opcional
Separar modelos de creación, actualización y respuesta con una base pequeña cuando aporte valor.
Contexto adicional
- Trabaja únicamente dentro del alcance del bloque: una aplicación pequeña y estado en memoria.
- No hay solución oficial publicada; el material contiene huecos y defectos deliberados.
- Justifica las decisiones por el mensaje HTTP y el contrato observable, no solo porque el código arranque.
Cómo revisar tu respuesta
- Creación no acepta campos asignados por el servidor.
- Update solo permite campos modificables.
- Salida no contiene `internal_note`.
Evidencia, revisión y reinicio
- Decisión razonada guardada localmente en la web.
- Código o informe ejecutable en el workspace temporal, más una captura de curl/OpenAPI cuando proceda.
Revisión: con Codex, utilizando la evidencia y los criterios anteriores; no se publica una solución oficial.
Reinicio: Eliminar el workspace temporal y volver a descargar el material inicial; no hay estado persistente externo.
Material descargable opcional
- API con modelo únicoStarter defectuoso con tres operaciones y una lista en memoria.
Teoría que puedes consultar
Transferencia: Puedes diseñar los modelos de otro recurso explicando propiedad, opcionalidad y reglas entre campos.
Paso 4 · Unidad 2.4
Alinea salida, errores y OpenAPI
Evidencia del paso: Status, headers, body, filtrado y documentación cuentan la misma historia pública.
Antes de ejecutar: Antes de editar, compara qué prometen status, headers, body, modelo de salida y OpenAPI.
Práctica guiada y focalizada
EX-B2-10
La respuesta filtra demasiado poco
Una respuesta devuelve el diccionario interno completo, incluidos `audit_token` y `owner_email`.
Pensar y responder en la web
Predice y guarda aquí tu razonamiento antes de abrir el material; después contrástalo en el workspace.
Pregunta central
¿Qué mecanismo convierte la lista permitida de campos en un contrato verificable?
Para ordenar tu razonamiento
- ¿Qué comportamiento observas y qué parte es todavía una hipótesis?
- ¿Cuál es el cambio mínimo que permite verificar la causa o el contrato?
- ¿Qué evidencia conservarías para demostrar que no rompiste otra frontera?
Trabajo en el workspace
- Captura la respuesta defectuosa.
- Añade un modelo público y `response_model`.
- Demuestra que los campos internos no aparecen en body ni esquema público.
Entrega esperada
- Implementación o propuesta mínima.
- Evidencia reproducible del caso principal y, al menos, un caso inválido.
- Nota breve con la decisión tomada y la alternativa descartada.
Escribe lo que piensas. Se guarda automáticamente en este navegador.
Sin respuesta guardada.
Pistas opcionales
Pista 1 · Localiza la frontera
- Separa importación, enrutado, extracción, validación, operación y serialización.
- Lee el status, los headers y la ubicación del error antes de editar.
Pista 2 · Reduce la prueba
- Usa una petición válida y una inválida que difieran en una sola variable.
- Compara el comportamiento con `/openapi.json` cuando el contrato esté documentado.
Profundización opcional
Introducir un modelo público que documente y filtre la salida.
Contexto adicional
- Trabaja únicamente dentro del alcance del bloque: una aplicación pequeña y estado en memoria.
- No hay solución oficial publicada; el material contiene huecos y defectos deliberados.
- Justifica las decisiones por el mensaje HTTP y el contrato observable, no solo porque el código arranque.
Cómo revisar tu respuesta
- La salida contiene solo campos públicos.
- OpenAPI referencia el modelo público.
- No se elimina la información únicamente con `dict.pop` ad hoc.
Evidencia, revisión y reinicio
- Decisión razonada guardada localmente en la web.
- Código o informe ejecutable en el workspace temporal, más una captura de curl/OpenAPI cuando proceda.
Revisión: con Codex, utilizando la evidencia y los criterios anteriores; no se publica una solución oficial.
Reinicio: Eliminar el workspace temporal y volver a descargar el material inicial; no hay estado persistente externo.
Material descargable opcional
- Endpoint con fuga de salidaAplicación mínima y checklist de regresión sin solución.
Teoría que puedes consultar
EX-B2-11
Tres formas de decir el mismo conflicto
Tres endpoints expresan una referencia duplicada con texto, `detail` arbitrario y status `200`.
Pensar y responder en la web
Predice y guarda aquí tu razonamiento antes de abrir el material; después contrástalo en el workspace.
Pregunta central
¿Qué campos necesita el consumidor para manejar el conflicto sin analizar texto humano?
Para ordenar tu razonamiento
- ¿Qué comportamiento observas y qué parte es todavía una hipótesis?
- ¿Cuál es el cambio mínimo que permite verificar la causa o el contrato?
- ¿Qué evidencia conservarías para demostrar que no rompiste otra frontera?
Trabajo en el workspace
- Diseña `ErrorEnvelope` y un código estable.
- Unifica las tres operaciones mediante una excepción de dominio o helper proporcionado.
- Documenta el `409` y prueba equivalencia de forma.
Entrega esperada
- Implementación o propuesta mínima.
- Evidencia reproducible del caso principal y, al menos, un caso inválido.
- Nota breve con la decisión tomada y la alternativa descartada.
Escribe lo que piensas. Se guarda automáticamente en este navegador.
Sin respuesta guardada.
Pistas opcionales
Pista 1 · Localiza la frontera
- Separa importación, enrutado, extracción, validación, operación y serialización.
- Lee el status, los headers y la ubicación del error antes de editar.
Pista 2 · Reduce la prueba
- Usa una petición válida y una inválida que difieran en una sola variable.
- Compara el comportamiento con `/openapi.json` cuando el contrato esté documentado.
Profundización opcional
Definir un error de negocio estable y una traducción HTTP uniforme.
Contexto adicional
- Trabaja únicamente dentro del alcance del bloque: una aplicación pequeña y estado en memoria.
- No hay solución oficial publicada; el material contiene huecos y defectos deliberados.
- Justifica las decisiones por el mensaje HTTP y el contrato observable, no solo porque el código arranque.
Cómo revisar tu respuesta
- El status es `409` en las tres rutas.
- Código y estructura son estables.
- El mensaje público no expone estado interno.
Evidencia, revisión y reinicio
- Decisión razonada guardada localmente en la web.
- Código o informe ejecutable en el workspace temporal, más una captura de curl/OpenAPI cuando proceda.
Revisión: con Codex, utilizando la evidencia y los criterios anteriores; no se publica una solución oficial.
Reinicio: Eliminar el workspace temporal y volver a descargar el material inicial; no hay estado persistente externo.
Material descargable opcional
- Errores inconsistentesTres endpoints parciales que representan el mismo conflicto.
Teoría que puedes consultar
EX-B2-12
Traducir 422 sin borrar la ubicación
Un manejador personalizado responde `Invalid request` para cualquier error y soporte ya no sabe qué campo falló.
Pensar y responder en la web
Predice y guarda aquí tu razonamiento antes de abrir el material; después contrástalo en el workspace.
Pregunta central
¿Cuál es el conjunto mínimo de señal pública que permite corregir la petición?
Para ordenar tu razonamiento
- ¿Qué comportamiento observas y qué parte es todavía una hipótesis?
- ¿Cuál es el cambio mínimo que permite verificar la causa o el contrato?
- ¿Qué evidencia conservarías para demostrar que no rompiste otra frontera?
Trabajo en el workspace
- Reproduce errores en path, query y body anidado.
- Transforma `exc.errors()` a una lista pública estable.
- Comprueba que `loc` distingue las tres fuentes y que el input crudo no se refleja.
Entrega esperada
- Implementación o propuesta mínima.
- Evidencia reproducible del caso principal y, al menos, un caso inválido.
- Nota breve con la decisión tomada y la alternativa descartada.
Escribe lo que piensas. Se guarda automáticamente en este navegador.
Sin respuesta guardada.
Pistas opcionales
Pista 1 · Localiza la frontera
- Separa importación, enrutado, extracción, validación, operación y serialización.
- Lee el status, los headers y la ubicación del error antes de editar.
Pista 2 · Reduce la prueba
- Usa una petición válida y una inválida que difieran en una sola variable.
- Compara el comportamiento con `/openapi.json` cuando el contrato esté documentado.
Profundización opcional
Transformar `RequestValidationError` conservando localización y tipo, y omitiendo input sensible.
Contexto adicional
- Trabaja únicamente dentro del alcance del bloque: una aplicación pequeña y estado en memoria.
- No hay solución oficial publicada; el material contiene huecos y defectos deliberados.
- Justifica las decisiones por el mensaje HTTP y el contrato observable, no solo porque el código arranque.
Cómo revisar tu respuesta
- La respuesta mantiene status `422`.
- Cada issue conserva fuente y ruta del campo.
- No se publica el body completo ni `str(exc)`.
Evidencia, revisión y reinicio
- Decisión razonada guardada localmente en la web.
- Código o informe ejecutable en el workspace temporal, más una captura de curl/OpenAPI cuando proceda.
Revisión: con Codex, utilizando la evidencia y los criterios anteriores; no se publica una solución oficial.
Reinicio: Eliminar el workspace temporal y volver a descargar el material inicial; no hay estado persistente externo.
Material descargable opcional
- Manejador que pierde contextoStarter y peticiones de regresión para tres ubicaciones.
Teoría que puedes consultar
EX-B2-13
Creado significa 201 y tiene ubicación
La creación funciona, pero devuelve `200`, no indica dónde quedó el recurso y documenta un modelo distinto.
Pensar y responder en la web
Predice y guarda aquí tu razonamiento antes de abrir el material; después contrástalo en el workspace.
Pregunta central
¿Qué debe poder deducir un cliente exclusivamente desde la respuesta?
Para ordenar tu razonamiento
- ¿Qué comportamiento observas y qué parte es todavía una hipótesis?
- ¿Cuál es el cambio mínimo que permite verificar la causa o el contrato?
- ¿Qué evidencia conservarías para demostrar que no rompiste otra frontera?
Trabajo en el workspace
- Declara `201` y el modelo público en el decorador.
- Añade un `Location` absoluto respecto al host.
- Verifica body, header, status y OpenAPI.
Entrega esperada
- Implementación o propuesta mínima.
- Evidencia reproducible del caso principal y, al menos, un caso inválido.
- Nota breve con la decisión tomada y la alternativa descartada.
Escribe lo que piensas. Se guarda automáticamente en este navegador.
Sin respuesta guardada.
Pistas opcionales
Pista 1 · Localiza la frontera
- Separa importación, enrutado, extracción, validación, operación y serialización.
- Lee el status, los headers y la ubicación del error antes de editar.
Pista 2 · Reduce la prueba
- Usa una petición válida y una inválida que difieran en una sola variable.
- Compara el comportamiento con `/openapi.json` cuando el contrato esté documentado.
Profundización opcional
Alinear status, header `Location`, body público y OpenAPI.
Contexto adicional
- Trabaja únicamente dentro del alcance del bloque: una aplicación pequeña y estado en memoria.
- No hay solución oficial publicada; el material contiene huecos y defectos deliberados.
- Justifica las decisiones por el mensaje HTTP y el contrato observable, no solo porque el código arranque.
Cómo revisar tu respuesta
- El status observado y documentado es `201`.
- `Location` resuelve al recurso creado.
- El body cumple el modelo público.
Evidencia, revisión y reinicio
- Decisión razonada guardada localmente en la web.
- Código o informe ejecutable en el workspace temporal, más una captura de curl/OpenAPI cuando proceda.
Revisión: con Codex, utilizando la evidencia y los criterios anteriores; no se publica una solución oficial.
Reinicio: Eliminar el workspace temporal y volver a descargar el material inicial; no hay estado persistente externo.
Material descargable opcional
- Creación parcialmente declaradaEndpoint en memoria con contrato de respuesta incompleto.
Teoría que puedes consultar
EX-B2-14
Revisión de PR desde OpenAPI
Un PR afirma implementar creación y consulta, pero el diff, los requisitos y el OpenAPI generado no coinciden.
Pensar y responder en la web
Predice y guarda aquí tu razonamiento antes de abrir el material; después contrástalo en el workspace.
Pregunta central
¿Qué divergencias rompen consumidores y cuáles son solo mejoras de estilo?
Para ordenar tu razonamiento
- ¿Qué comportamiento observas y qué parte es todavía una hipótesis?
- ¿Cuál es el cambio mínimo que permite verificar la causa o el contrato?
- ¿Qué evidencia conservarías para demostrar que no rompiste otra frontera?
Trabajo en el workspace
- Construye una matriz requisito → OpenAPI → implementación.
- Prioriza hallazgos por impacto observable.
- Propón cambios mínimos sin reescribir la arquitectura.
- Incluye al menos una comprobación positiva y una negativa.
Entrega esperada
- Implementación o propuesta mínima.
- Evidencia reproducible del caso principal y, al menos, un caso inválido.
- Nota breve con la decisión tomada y la alternativa descartada.
Escribe lo que piensas. Se guarda automáticamente en este navegador.
Sin respuesta guardada.
Pistas opcionales
Pista 1 · Localiza la frontera
- Separa importación, enrutado, extracción, validación, operación y serialización.
- Lee el status, los headers y la ubicación del error antes de editar.
Pista 2 · Reduce la prueba
- Usa una petición válida y una inválida que difieran en una sola variable.
- Compara el comportamiento con `/openapi.json` cuando el contrato esté documentado.
Profundización opcional
Realizar una revisión contractual con hallazgos priorizados y evidencia precisa.
Contexto adicional
- Trabaja únicamente dentro del alcance del bloque: una aplicación pequeña y estado en memoria.
- No hay solución oficial publicada; el material contiene huecos y defectos deliberados.
- Justifica las decisiones por el mensaje HTTP y el contrato observable, no solo porque el código arranque.
Cómo revisar tu respuesta
- Cada hallazgo cita una evidencia verificable.
- Se revisan método, fuentes, schemas, status, headers y errores.
- No se confunden preferencias de estilo con defectos del contrato.
Evidencia, revisión y reinicio
- Decisión razonada guardada localmente en la web.
- Código o informe ejecutable en el workspace temporal, más una captura de curl/OpenAPI cuando proceda.
Revisión: con Codex, utilizando la evidencia y los criterios anteriores; no se publica una solución oficial.
Reinicio: Eliminar el workspace temporal y volver a descargar el material inicial; no hay estado persistente externo.
Material descargable opcional
- Paquete de revisiónRequisitos, extracto de diff y documento OpenAPI 3.1 válido con discrepancias contractuales deliberadas.
Teoría que puedes consultar
Transferencia: Puedes revisar otra API desde la perspectiva de un consumidor y detectar una promesa no cumplida.
Retira apoyo con 2 series progresivas
EX-B2-S01 pasa de guiado alto a ligero. EX-B2-S02 termina con una cuarta parte autónoma. Conserva un checkpoint aceptado antes de avanzar, porque cada parte reutiliza el contrato anterior.
EX-B2-S01
Admisiones internas por contrato
Un equipo necesita recibir solicitudes de admisión, consultar su estado y rechazar entradas incoherentes antes de incorporar persistencia.
Abrir práctica extendida: base común y 3 partes
Base común
- El identificador lo asigna el servidor y todo el estado vive en memoria.
- La referencia pública, el departamento y el periodo se validan; no hay login ni base de datos.
- Cada parte parte del checkpoint aceptado de la anterior.
Paquete de trabajo
- Starter de la serie de admisionesProyecto parcial, peticiones y plantilla de checkpoints sin solución.
Entorno, evidencia y reinicio
Entorno: Workspace temporal con Python 3.10+, uv, FastAPI y Pydantic 2; estado en memoria.
- Tres checkpoints ejecutables y un OpenAPI por parte.
- Matriz de peticiones válidas e inválidas con status, headers y body.
Revisión: con Codex, utilizando los artefactos y criterios de cada parte; no se publica una solución oficial.
Reinicio: Eliminar el workspace de la serie y volver a descargar el starter; cada parte conserva un checkpoint separado.
Parte 1 · Apoyo alto
EX-B2-S01-P1 · Rutas y fuentes HTTP
Definir creación, consulta y listado con sus fuentes, obligatoriedad y status provisionales.
Qué debes hacer
- Implementa las tres operaciones sobre una lista en memoria.
- Declara correlación y paginación sin mezclarlas con el body.
- Compara firmas y OpenAPI con la matriz del starter.
Entrega esperada
- Checkpoint P1
- openapi-p1.json
- evidence-p1.md
Criterios de aceptación
- Métodos y rutas son coherentes con identidad y colección.
- Las fuentes aparecen correctamente en OpenAPI.
- No existe infraestructura fuera de alcance.
Evidencia para revisión
- OpenAPI con las rutas y fuentes acordadas.
- Cuatro peticiones curl que distingan path, query, header y body.
Reinicio de esta parte: Conservar el checkpoint anterior fuera del starter o volver a descomprimir una copia limpia para repetir esta parte.
Pista · Diseña desde HTTP
- Empieza por método, path y status; después escribe la firma.
Parte 2 · Apoyo moderado
EX-B2-S01-P2 · Modelos y reglas
Separar create, update y public; añadir enums, anidación y una regla cruzada.
Qué debes hacer
- Modela solicitante, periodo y estado.
- Ubica restricciones y validadores en el nivel adecuado.
- Implementa patch parcial conservando campos omitidos.
Entrega esperada
- Checkpoint P2
- model-matrix.md
- invalid-cases.md
Criterios de aceptación
- Los modelos de operación están separados.
- La regla cruzada produce una localización útil.
- El patch no pisa campos ausentes.
Evidencia para revisión
- Modelos Pydantic y errores de muestras.
- Diferencia demostrada entre omitido y null.
Reinicio de esta parte: Conservar el checkpoint anterior fuera del starter o volver a descomprimir una copia limpia para repetir esta parte.
Pista · Propiedad de los campos
- Marca primero quién asigna y quién puede modificar cada campo.
Parte 3 · Apoyo ligero
EX-B2-S01-P3 · Salida y errores
Cerrar el contrato observable con filtrado, estados, Location y errores consistentes.
Qué debes hacer
- Aplica modelos públicos a todas las respuestas.
- Añade `201` y `Location` a creación.
- Unifica not found, conflicto y validación.
- Documenta las respuestas adicionales.
Entrega esperada
- Checkpoint P3
- openapi-final.json
- contract-evidence.md
Criterios de aceptación
- No se filtran notas internas.
- Errores y éxitos coinciden con OpenAPI.
- La colección sigue siendo puramente en memoria.
Evidencia para revisión
- Respuestas públicas, Location y errores uniformes.
- OpenAPI final y regresión de filtrado.
Reinicio de esta parte: Conservar el checkpoint anterior fuera del starter o volver a descomprimir una copia limpia para repetir esta parte.
Pista · Revisa como cliente
- Inspecciona status, headers y body; no solo el valor devuelto por Python.
Teoría que puedes consultar
EX-B2-S02
Incidentes en una API de reparaciones
Una API pequeña arranca, pero interpreta mal entradas, acepta estados imposibles, devuelve errores incompatibles y filtra datos de taller.
Abrir práctica extendida: base común y 4 partes
Base común
- Cada parte corrige una frontera y añade una regresión.
- No se permite una reescritura total: primero se demuestra la causa.
- El estado continúa en memoria y todas las personas y referencias son sintéticas.
Paquete de trabajo
- API defectuosa de reparacionesStarter, matriz de incidentes y tráfico capturado.
Entorno, evidencia y reinicio
Entorno: Workspace temporal con una aplicación FastAPI deliberadamente defectuosa y datos sintéticos.
- Cuatro checkpoints de reparación.
- Registro de hipótesis, cambios mínimos y regresiones.
Revisión: con Codex, utilizando los artefactos y criterios de cada parte; no se publica una solución oficial.
Reinicio: Restaurar el starter descargado y repetir desde la petición que reproduce el incidente.
Parte 1 · Apoyo alto
EX-B2-S02-P1 · Entradas en la fuente equivocada
Corregir path, query y header a partir del tráfico observado.
Qué debes hacer
- Clasifica dos fallos como enrutado o extracción.
- Modifica firmas y orden con el cambio mínimo.
- Añade peticiones de regresión.
Entrega esperada
- Checkpoint P1
- incident-log-p1.md
Criterios de aceptación
- La causa se reproduce antes de editar.
- OpenAPI y tráfico esperado coinciden.
Evidencia para revisión
- Reproducción de los fallos de fuente.
- OpenAPI corregido sin cambios de dominio.
Reinicio de esta parte: Conservar el checkpoint anterior fuera del starter o volver a descomprimir una copia limpia para repetir esta parte.
Pista
- Una respuesta 404 no demuestra un fallo de validación.
Parte 2 · Apoyo moderado
EX-B2-S02-P2 · La frontera de validación
Reubicar restricciones, enums y una relación de fechas.
Qué debes hacer
- Separa reglas de campo, modelo y negocio.
- Cierra el vocabulario de estados.
- Demuestra tres errores con ubicaciones diferentes.
Entrega esperada
- Checkpoint P2
- validation-evidence.md
Criterios de aceptación
- No hay estado externo en validadores.
- Las reglas cruzadas se ejecutan sobre datos ya tipados.
Evidencia para revisión
- Errores Pydantic localizables.
- Matriz de reglas antes/después.
Reinicio de esta parte: Conservar el checkpoint anterior fuera del starter o volver a descomprimir una copia limpia para repetir esta parte.
Pista
- Usa `Field` antes de escribir lógica imperativa.
Parte 3 · Apoyo ligero
EX-B2-S02-P3 · Contrato de excepciones
Unificar conflictos, ausencias y validación sin perder señal.
Qué debes hacer
- Define códigos estables y status por condición.
- Implementa manejadores proporcionados.
- Verifica que la respuesta no refleja excepciones internas.
Entrega esperada
- Checkpoint P3
- error-contract.md
Criterios de aceptación
- Cada condición tiene una única forma pública.
- La validación conserva localización.
Evidencia para revisión
- Errores públicos equivalentes por condición.
- Ausencia de detalles internos en respuestas.
Reinicio de esta parte: Conservar el checkpoint anterior fuera del starter o volver a descomprimir una copia limpia para repetir esta parte.
Pista
- El texto humano puede cambiar; el código de error no debería.
Parte 4 · Apoyo autónomo
EX-B2-S02-P4 · Filtrado y regresión final
Cerrar la fuga de salida y probar el contrato completo.
Qué debes hacer
- Añade modelos públicos por operación.
- Comprueba que `workshop_note` no sale.
- Ejecuta la matriz de incidentes completa.
- Entrega el OpenAPI y las diferencias observables.
Entrega esperada
- Checkpoint P4
- openapi-final.json
- regression-report.md
Criterios de aceptación
- El campo interno no aparece en respuestas ni schemas públicos.
- Todas las regresiones anteriores siguen pasando.
Evidencia para revisión
- Regresión que falla antes y pasa después.
- OpenAPI final sin campos internos.
Reinicio de esta parte: Conservar el checkpoint anterior fuera del starter o volver a descomprimir una copia limpia para repetir esta parte.
Pista
- Filtra por contrato, no borrando claves después de construir la respuesta.
Teoría que puedes consultar
Transferencia del tramo · Miniproyecto recomendado
MP-B2-R · Recomendado
Validador de expedientes internos
Construye una API pequeña que admita expedientes sintéticos, los valide y publique una representación segura antes de incorporar persistencia.