Práctica del bloque 1 · Kiril Ferrer López

Cómo trabajar este bloque

Abre un ejercicio, lee la pregunta y responde en su cuadro de texto o selecciona una opción. El guardado es automático y local: no se envía a ningún servidor.

Las descargas, criterios detallados y materiales largos quedan dentro de Profundización opcional. Las dos series y el caso profesional sí son prácticas extensas para cuando quieras trabajar con más proceso.

Ver y revisar las respuestas guardadas

Ejercicios independientes

Son preguntas breves y autocontenidas. No requieren descargar archivos ni redactar un documento formal.

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é diferencia exacta existe entre el contrato y la petición enviada, y cómo quedaría el comando `curl` mínimo que corrige esa diferencia?

Información que necesitas

Endpoint requirement
PATCH /v1/records/{record_id}
Content-Type: application/merge-patch+json
Body fields: state (draft | in_review | closed), notify (boolean)

Reproduction
curl --include --request PATCH \
  'https://records.internal.example/v1/records/REC-204' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"state":"in_review","notify":false}'

HTTP/1.1 415 Unsupported Media Type
Content-Type: application/problem+json
Content-Length: 108
X-Request-ID: req-8f21

{"title":"Unsupported Media Type","status":415,"detail":"Content-Type must be application/merge-patch+json"}

Para ordenar tu razonamiento

Localiza el media type exigido por el contrato y el que envía el cliente.
Relaciona esa divergencia con el status `415` y con el campo `detail` de la respuesta.
Corrige solo el header necesario y explica por qué el intercambio no demuestra todavía que el payload será aceptado.

Trabajo en el workspace

Compara el requisito del endpoint con el comando ejecutado y enumera solo las diferencias observables.
Explica por qué `415` señala el formato declarado por la request y no un error de sintaxis del JSON ni un recurso inexistente.
Escribe el comando `curl` corregido conservando método, URL, `Accept` y payload.
Indica qué comprobarías en una segunda ejecución y qué valor usarías para correlacionarla con logs del servidor.

Entrega esperada

Diagnóstico de causa con citas del requisito y de la respuesta.
Comando `curl` corregido.
Dos comprobaciones para la siguiente ejecución: una de transporte y otra del resultado de negocio.

Tu razonamiento

Escribe lo que piensas. Se guarda automáticamente en este navegador.

Sin respuesta guardada.

Pistas opcionales

Pista 1 · Compara contrato y request

Busca el mismo concepto —`Content-Type`— en el requisito y en el comando.
Método, ruta y campos del body ya coinciden; no los cambies sin evidencia.

Pista 2 · Usa la respuesta

`415` significa que el servidor rechaza el media type de la representación enviada.
El campo `detail` nombra además el valor que exige el endpoint.

Pista 3 · Limita la conclusión

Corregir este header elimina una causa demostrada, pero no ejecuta por sí solo las reglas de negocio.
Conserva `req-8f21` para investigar el intento original; una nueva ejecución normalmente recibirá otro identificador.

Profundización opcional

Demostrar por qué el servidor devuelve `415 Unsupported Media Type` y preparar la corrección mínima de la petición sin cambiar datos que no están relacionados con el fallo.

Contexto adicional

El endpoint exige `application/merge-patch+json` porque el body describe una actualización parcial, no la representación completa del recurso.
El comando de reproducción usa el método y la ruta correctos, pero declara otro `Content-Type`.
La respuesta incluye status, media type, un detalle legible y `X-Request-ID`; no necesitas reconstruir información ausente.

Cómo revisar tu respuesta

La causa se identifica como la divergencia entre `application/json` y `application/merge-patch+json`.
El comando corregido no cambia `PATCH`, la URL ni el JSON.
La explicación usa el `415` y el campo `detail` como evidencia, no como suposición.
No se afirma que la segunda petición vaya a responder `200`; aún pueden fallar autenticación, versión, validación o reglas de negocio.
`X-Request-ID: req-8f21` se reconoce como identificador útil para buscar la ejecución rechazada en logs.

Evidencia, revisión y reinicio

Respuesta razonada guardada localmente en el navegador.
Diagnóstico basado en evidencia y comando `curl` corregido.

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 una copia limpia de los materiales opcionales.

Material descargable opcional

Ticket de integraciónRequisito, comando de reproducción y respuesta HTTP observada.
Plantilla de diagnósticoTabla para unir requisito, evidencia, impacto y cambio mínimo.

Teoría que puedes consultar

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é status corresponde a cada resultado según la política declarada y qué acción permite tomar al consumidor?

Información que necesitas

Política de la API
- JSON bien formado que incumple el schema: 422.
- Dependencia temporalmente no disponible: 503.

Resultados observados
A. GET /documents devuelve 18 elementos.
B. POST /records crea REC-204 y emite Location: /records/REC-204.
C. PATCH /records/REC-204 recibe {"closed_at":"tomorrow"}; el schema exige date-time ISO 8601.
D. GET /records/REC-999 usa un id válido que no existe.
E. POST /records recibe external_reference=REF-77, ya asociada a otro registro.
F. Una petición válida no termina porque la base de datos está temporalmente fuera de servicio.

Para ordenar tu razonamiento

Clasifica primero cada situación como éxito, problema del cliente o fallo del servidor.
Elige un código concreto para A–F y justifícalo con una frase.
Justifica cada elección con el hecho observable que la determina.

Trabajo en el workspace

Asigna a cada situación una familia 2xx, 4xx o 5xx antes de escoger un código concreto.
Selecciona un código de estado y justifícalo desde la perspectiva del consumidor.
Indica qué acción razonable puede tomar el consumidor: continuar, corregir, dejar de buscar, resolver el conflicto o reintentar más tarde.

Entrega esperada

Seis selecciones con una justificación y una acción del consumidor por caso.

Pistas opcionales

Pista 1 · Decide primero la responsabilidad

Pregunta si una petición idéntica podría funcionar sin cambiar nada del servidor.
Después concreta el código dentro de la familia elegida.

Pista 2 · Conflicto no significa sintaxis inválida

Una representación puede estar bien formada y aun así chocar con el estado actual del sistema.

Profundización opcional

Seleccionar familias y códigos de estado adecuados, diferenciando éxito, error del cliente y error del servidor.

Contexto adicional

No basta con escribir un número: cada elección debe relacionarse con lo que ocurrió y con la acción que puede tomar el cliente.
No inventes supuestos alternativos: la política de `422` y `503` forma parte del enunciado.

Cómo revisar tu respuesta

No se utiliza 200 como respuesta universal.
Los errores provocados por datos del cliente no se clasifican como fallos internos.
La creación se distingue de una lectura satisfactoria cuando el servidor crea un recurso identificable.
La justificación describe comportamiento observable y no detalles de implementación.

Evidencia, revisión y reinicio

Selecciones razonadas guardadas localmente en el navegador.
Matriz de estados completada si se utiliza el material opcional.

Revisión: con Codex, utilizando la evidencia y los criterios anteriores; no se publica una solución oficial.

Reinicio: Borrar las selecciones desde la tarjeta y volver a descargar una matriz vacía cuando se necesite reiniciar.

Material descargable opcional

Matriz de incidentesPlantilla breve para status, evidencia y acción del consumidor.

Teoría que puedes consultar

Unidad 1.1 · Códigos de estado

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

¿Cómo representarías documentos, autores y préstamos como recursos sin convertir cada acción del enunciado en una ruta con un verbo?

Para ordenar tu razonamiento

Propón una ruta de colección y una ruta individual para cada recurso imprescindible.
Elige método y resultado esperado para abrir y finalizar un préstamo.
Explica qué ocurriría si el cliente repite la petición después de perder la respuesta.

Trabajo en el workspace

Lee el diccionario técnico y propón únicamente las operaciones necesarias para listar y consultar documentos, abrir un préstamo y registrar su devolución.
Para cada operación indica método, ruta, entrada principal y resultado observable.
Explica en dos o tres frases cómo manejas un reintento de creación y la devolución del préstamo.
Declara los supuestos que el brief no resuelve; no diseñes autenticación, persistencia ni endpoints adicionales.

Entrega esperada

Propuesta compacta de operaciones y hasta tres supuestos de diseño.
Una nota breve sobre reintentos y devolución del préstamo.

Tu razonamiento

Escribe lo que piensas. Se guarda automáticamente en este navegador.

Sin respuesta guardada.

Pistas opcionales

Pista 1 · Sustantivos antes que rutas

Empieza por qué entidades reconoce el negocio y cuáles poseen identidad.
No conviertas cada frase de los requisitos en un endpoint.

Pista 2 · Piensa en la repetición

Para cada operación de escritura, imagina que la respuesta se pierde y el cliente repite exactamente la petición.

Profundización opcional

Diseñar un contrato HTTP coherente mediante recursos, rutas, métodos y estados, separando sustantivos de acciones.

Contexto adicional

Existen documentos, autores y préstamos con identificadores estables.
Un documento puede tener varios autores y puede estar disponible o prestado.
Los consumidores deben listar y filtrar documentos, consultar un documento, abrir un préstamo y registrar su finalización.
La referencia del préstamo la asigna el servidor.
Un cliente puede repetir una petición después de perder la respuesta por un timeout.

Decisiones abiertas

Cómo expresar la devolución o cierre del préstamo.
Si la relación documento-autor necesita operaciones propias en el alcance mínimo.
Qué filtros pertenecen a la colección de documentos.

Cómo revisar tu respuesta

Las rutas expresan recursos y no una colección arbitraria de verbos remotos.
Colección y elemento individual se distinguen de forma consistente.
La apertura de un préstamo no se presenta como idempotente sin una condición adicional explícita.
El contrato contempla recurso inexistente y conflicto de disponibilidad.
La decisión abierta se documenta sin fingir que existe una única respuesta universal.

Evidencia, revisión y reinicio

Respuesta de diseño guardada localmente en el navegador.
Contrato de operaciones y decisiones justificadas en 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 las plantillas originales antes de un nuevo intento.

Material descargable opcional

Requisitos del contratoEncargo completo, restricciones de identidad y preguntas abiertas.
Plantilla de operacionesPlantilla compacta de operaciones, supuestos, reintentos y devolución.

Teoría que puedes consultar

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é fragmentos no son JSON, cuáles sí son JSON pero incumplen el contrato y cuál aceptarías tal como está?

Información que necesitas

Fragmento A
{'id': 'doc-7', 'title': 'Quarterly report', 'published': True,}

Fragmento B
{"id": 7, "title": "Quarterly report", "tags": "api,http", "published": "false",
 "summary": null, "owner": {"id": "u-3", "name": "Ada"}}

Fragmento C
{"id": "doc-8", "title": "Board minutes", "tags": ["archive", 2026],
 "published": false, "owner": null}

Fragmento D
{"id": "doc-9", "title": "Release notes", "tags": [],
 "published": true, "owner": {"id": "u-8", "name": "Lin"}}

Para ordenar tu razonamiento

Clasifica A–D antes de intentar corregirlos.
Nombra el primer problema concreto que encuentres en cada fragmento.
Explica por qué null y un campo ausente no significan necesariamente lo mismo.

Trabajo en el workspace

Determina para cada fragmento si puede analizarse como JSON.
Solo para los fragmentos sintácticamente válidos, contrasta cada campo con el contrato.
Distingue campo ausente, valor null, string vacío y valor predeterminado cuando aparezcan o sean relevantes.
Propón el cambio mínimo que permitiría volver a evaluar cada fragmento, sin inventar datos de negocio.

Entrega esperada

Hoja de diagnóstico para los cuatro fragmentos.
Lista de correcciones separada en sintaxis y contrato.

Pistas opcionales

Pista 1 · Dos preguntas distintas

Primero pregunta si un parser JSON podría leer el texto.
Después pregunta si el valor obtenido satisface el contrato.

Pista 2 · Revisa literales y comillas

JSON no utiliza exactamente los mismos literales ni las mismas reglas de comillas que Python.

Pista 3 · Recorre la estructura

No te detengas en los campos de primer nivel: revisa elementos de arrays y objetos anidados.

Profundización opcional

Distinguir errores de sintaxis JSON de desacuerdos semánticos con un contrato, atendiendo a tipos, arrays, ausencia y null.

Contexto adicional

Contrato de referencia: id es string requerido; title es string requerido; tags es array de strings; published es boolean; summary puede ser string o null; owner es un objeto con id y name.
La ausencia de summary está permitida. La ausencia de id, title u owner no lo está.
No corrijas automáticamente los datos: primero clasifica y explica cada fallo.

Cómo revisar tu respuesta

No se valida el contrato de un fragmento antes de resolver su sintaxis JSON.
String, número, boolean y array no se consideran intercambiables por su apariencia.
Null no se interpreta como ausencia.
Un fragmento válido y conforme se reconoce sin introducir cambios innecesarios.

Evidencia, revisión y reinicio

Clasificación de fragmentos guardada localmente en el navegador.
Diagnóstico por fragmento 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 las selecciones desde la tarjeta y descargar de nuevo los payloads y la plantilla sin modificar.

Material descargable opcional

Colección de payloadsFragmentos sin modificar, incluidos los que contienen sintaxis inválida.
Hoja de diagnósticoPlantilla para validez sintáctica, cumplimiento del contrato y cambio mínimo propuesto.

Teoría que puedes consultar

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

Leyendo solo el documento OpenAPI, ¿qué petición válida harías para buscar obras y qué respuestas puede recibir un consumidor?

Documento OpenAPI

openapi: 3.1.0
info:
  title: Local culture catalog
  version: 1.0.0
servers:
  - url: https://catalog.example.test/v1
paths:
  /works:
    get:
      operationId: listWorks
      summary: Search catalog works
      parameters:
        - name: q
          in: query
          required: false
          schema:
            type: string
            minLength: 2
        - name: type
          in: query
          required: false
          schema:
            type: string
            enum: [painting, sculpture, photograph]
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 50
            default: 20
      responses:
        "200":
          description: Filtered collection
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkCollection"
        "400":
          description: Invalid query parameter
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Problem"
  /works/{work_id}:
    get:
      operationId: getWork
      summary: Get a work
      parameters:
        - name: work_id
          in: path
          required: true
          schema:
            type: string
            pattern: "^wrk-[0-9]+$"
      responses:
        "200":
          description: Work found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Work"
        "404":
          description: Work not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Problem"
components:
  schemas:
    Work:
      type: object
      required: [id, title, type]
      properties:
        id:
          type: string
        title:
          type: string
        type:
          type: string
          enum: [painting, sculpture, photograph]
        author:
          type: [string, "null"]
        year:
          type: [integer, "null"]
    WorkCollection:
      type: object
      required: [items, total]
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/Work"
        total:
          type: integer
          minimum: 0
    Problem:
      type: object
      required: [code, message]
      properties:
        code:
          type: string
        message:
          type: string

Para ordenar tu razonamiento

Localiza la URL base, la ruta, el método y los parámetros disponibles.
Distingue qué parámetros son opcionales y qué límites tienen.
Describe una respuesta satisfactoria y un error siguiendo los schemas referenciados.

Trabajo en el workspace

Identifica servidor, rutas, métodos y finalidad de cada operationId.
Enumera los parámetros, su ubicación, tipo, obligatoriedad y restricciones visibles.
Construye una petición válida para cada operación sin ejecutarla.
Describe la forma de una respuesta satisfactoria y de dos respuestas de error.
Señala una decisión que el contrato deja sin aclarar y formula una pregunta para el proveedor.

Entrega esperada

Cuestionario respondido con referencias a rutas, parámetros, responses y components.
Dos peticiones HTTP completas que respeten el contrato.
Descripción de una respuesta satisfactoria y dos errores.

Tu razonamiento

Escribe lo que piensas. Se guarda automáticamente en este navegador.

Sin respuesta guardada.

Pistas opcionales

Pista 1 · Recorre el contrato en capas

Empieza por servers y paths; después baja a cada método, parameters y responses.
Deja components para cuando encuentres una referencia.

Pista 2 · Separa descripción y restricción

Una descripción explica intención; type, enum, minimum y required restringen valores.

Profundización opcional

Deducir entradas, salidas, obligatoriedad y errores directamente desde un documento OpenAPI 3.1.

Contexto adicional

El contrato contiene una consulta de colección y una consulta individual.
No se pide implementar un cliente ni memorizar toda la especificación OpenAPI.
Cada afirmación debe señalar el elemento del contrato que la respalda.

Cómo revisar tu respuesta

Los parámetros de path y query no se intercambian.
La obligatoriedad se obtiene de required y no de la intuición.
Las referencias $ref se siguen hasta el schema correspondiente.
La lectura funciona sin depender de Swagger UI.

Evidencia, revisión y reinicio

Lectura razonada guardada localmente en el navegador.
Cuestionario de contrato completado si se usa el material 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 descargar otra copia del contrato y cuestionario originales.

Material descargable opcional

Contrato OpenAPIEspecificación local, reducida y válida para un catálogo cultural ficticio.
Cuestionario de lecturaPreguntas sobre operaciones, parámetros, schemas y respuestas.

Teoría que puedes consultar

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

Si la primera respuesta se pierde y el cliente repite exactamente la petición, ¿qué operaciones son seguras, idempotentes o arriesgadas de reintentar?

Información que necesitas

1. GET /reservations/{reservation_id} — consulta una reserva y registra métricas de lectura.
2. HEAD /rooms/{room_id}/availability — devuelve únicamente cabeceras.
3. POST /charges — crea un cargo nuevo por cada petición aceptada.
4. PUT /users/{user_id}/preferences — sustituye todas las preferencias por el body.
5. DELETE /subscriptions/{subscription_id} — elimina la suscripción si existe.
6. PATCH /orders/{order_id} — incrementa `delivery_attempts` en 1.
7. POST /webhooks/deliveries — registra la entrega; `delivery_key` evita duplicados.

Para ordenar tu razonamiento

Clasifica las siete operaciones en segura/no segura e idempotente/no idempotente.
Compara el estado tras una ejecución con el estado tras dos peticiones iguales.
Elige el caso más engañoso y explica la confusión habitual.

Trabajo en el workspace

Clasifica cada operación como segura o no segura.
Clasifica cada operación como idempotente o no idempotente según la descripción.
Predice el estado observable después de repetir dos veces una petición idéntica.
Propón una decisión de reintento tras timeout: automático, condicionado o manual.
Identifica el dato adicional que podría cambiar la clasificación de la operación de webhooks.

Entrega esperada

Tabla completa de las siete operaciones.
Justificación breve de los dos casos que consideres más propensos a confusión.

Pistas opcionales

Pista única · Compara el estado final

Para idempotencia, compara el estado relevante tras una ejecución con el estado tras varias peticiones idénticas.

Profundización opcional

Clasificar operaciones HTTP por seguridad e idempotencia y predecir el riesgo de repetirlas cuando la primera respuesta se pierde.

Contexto adicional

Clasifica la operación por su comportamiento prometido, no solo por el nombre del método.
Diferencia que una operación sea idempotente de que siempre tenga éxito o carezca de efectos secundarios.

Cómo revisar tu respuesta

Seguro e idempotente se evalúan como propiedades distintas.
Registrar métricas no invalida automáticamente la intención segura de una lectura.
La idempotencia no se confunde con obtener la misma representación o el mismo código en cada intento.
Los reintentos consideran el efecto de una primera ejecución cuya respuesta se perdió.

Evidencia, revisión y reinicio

Clasificaciones guardadas localmente en el navegador.
Justificación del efecto de repetición si se completa la tabla opcional.

Revisión: con Codex, utilizando la evidencia y los criterios anteriores; no se publica una solución oficial.

Reinicio: Borrar las selecciones desde la tarjeta y volver a descargar la tabla de operaciones original.

Material descargable opcional

Tabla de operacionesMatriz vacía para semántica, repetición, riesgo y política de reintento.

Teoría que puedes consultar

Unidad 1.1 · Semántica de métodos

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é tramo explica la mayor parte de la latencia observada y qué evidencia permite atribuirlo al servidor o a la red?

Información que necesitas

$ curl --silent --output response.json --dump-header response.headers \
  --write-out 'dns=%{time_namelookup} connect=%{time_connect} first_byte=%{time_starttransfer} total=%{time_total} status=%{http_code}\n' \
  'https://records.internal.example/v1/records/REC-204'
dns=0.018 connect=0.061 first_byte=0.302 total=0.306 status=200

$ grep -i x-request-id response.headers
X-Request-ID: req-7ac2

{"event":"request.complete","request_id":"req-7ac2","method":"GET","route":"/v1/records/{record_id}","status":200,"duration_ms":217,"db_ms":182,"serialize_ms":4}

Para ordenar tu razonamiento

Calcula cada tramo restando los tiempos acumulados de `curl`.
Usa `req-7ac2` para demostrar que el log pertenece a la misma petición.
Compara `duration_ms` con `db_ms` y decide qué investigar después.

Trabajo en el workspace

Calcula DNS, establecimiento de conexión, intervalo desde conexión hasta primer byte y transferencia del body.
Correlaciona la medición del cliente con el log mediante `X-Request-ID`.
Compara la duración total del servidor con el tiempo hasta el primer byte.
Redacta un hallazgo principal y una única comprobación siguiente que pueda confirmar la causa.

Entrega esperada

Cuatro tramos calculados en milisegundos.
Nota de incidente de hasta cinco frases con hallazgo, evidencia y siguiente comprobación.

Tu razonamiento

Escribe lo que piensas. Se guarda automáticamente en este navegador.

Sin respuesta guardada.

Pistas opcionales

Pista 1 · Los hitos son acumulados

La conexión adicional es `time_connect - time_namelookup`, no 61 + 18.

Pista 2 · Une ambas fuentes

El mismo request ID aparece en la respuesta guardada y en el log estructurado.

Profundización opcional

Separar DNS, conexión, espera hasta el primer byte, transferencia y trabajo del servidor para elegir el siguiente punto de investigación.

Contexto adicional

Los tiempos de `curl` son acumulados desde el comienzo; calcula un tramo restando el hito anterior.
`time_starttransfer` incluye conexión, envío, trabajo del servidor y viaje del primer byte.
No atribuyas automáticamente todo el tiempo restante a la red: compáralo con `duration_ms`.

Cómo revisar tu respuesta

Los tiempos acumulados no se suman entre sí.
DNS se calcula como 18 ms, conexión adicional como 43 ms y transferencia como 4 ms.
El log se vincula por `req-7ac2`, no solo porque la ruta coincide.
Los 182 ms de base de datos se reconocen como el componente medido dominante dentro de los 217 ms del servidor.
La conclusión distingue medición de hipótesis y propone inspeccionar la consulta o su plan antes de optimizar otra capa.

Evidencia, revisión y reinicio

Diagnóstico de latencia guardado localmente en el navegador.
Cálculos de tramos y evidencia de correlación.

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 la evidencia y la plantilla originales.

Material descargable opcional

Evidencia del incidenteComando `curl`, timings, header de correlación y log del servidor.
Plantilla de diagnósticoCálculos de tramos, hallazgo principal y siguiente comprobación.

Teoría que puedes consultar

Unidad 1.1 · Flujo completo de una interacción

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é endpoints son candidatos razonables para I/O asíncrono y cuál no debe ejecutar su trabajo de CPU directamente en el event loop?

Información que necesitas

Profile window: 100 local requests, median per request, one process worker

GET /shipping-quotes
cpu_ms=7 upstream_wait_ms=418 file_wait_ms=0

POST /reports/monthly
cpu_ms=870 file_wait_ms=34 upstream_wait_ms=0

POST /imports
cpu_ms=312 upload_read_wait_ms=48 webhook_wait_ms=195

Constraints
- The shipping provider and webhook clients expose non-blocking APIs.
- PDF generation is a synchronous CPU-bound function.
- No extra process or background job system is active in this measurement.

Para ordenar tu razonamiento

Identifica la fase dominante de cada endpoint.
Recomienda `async`, mantener código síncrono o separar trabajo, citando la medición.
Explica qué mejora esperas concurrentes y qué requeriría paralelismo u otro diseño.

Trabajo en el workspace

Clasifica el cuello dominante de cada endpoint como espera externa, CPU o carga mixta.
Escribe una recomendación de una o dos frases por endpoint vinculada a los milisegundos medidos.
Señala qué llamada debe ser realmente no bloqueante para que `async` aporte concurrencia.
Explica por qué convertir el generador de PDF a `async def` no reduce sus 870 ms de CPU.

Entrega esperada

Tres recomendaciones breves, una por endpoint.
Una conclusión que distinga concurrencia de paralelismo y proponga la siguiente medición.

Tu razonamiento

Escribe lo que piensas. Se guarda automáticamente en este navegador.

Sin respuesta guardada.

Pistas opcionales

Pista 1 · Compara magnitudes

418 frente a 7 describe un perfil muy distinto de 870 frente a 34.

Pista 2 · Async necesita I/O no bloqueante

Una función `async def` que llama a una librería bloqueante sigue bloqueando el event loop.

Pista 3 · Separa CPU

La concurrencia permite aprovechar esperas; acelerar cálculo activo exige paralelismo, optimización o sacar el trabajo de la request.

Profundización opcional

Usar mediciones para decidir dónde `async` puede mejorar concurrencia, dónde no acelera el trabajo y qué riesgo evitar en el event loop.

Contexto adicional

Las medidas son medianas de 100 peticiones locales y no demuestran por sí solas la capacidad máxima.
El cliente HTTP del proveedor y el cliente del webhook disponen de API no bloqueante.
El generador de PDF es una función síncrona que mantiene ocupada la CPU mientras trabaja.

Cómo revisar tu respuesta

`GET /shipping-quotes` se identifica como candidato claro a I/O asíncrono por sus 418 ms de espera frente a 7 ms de CPU.
`POST /reports/monthly` no se recomienda como conversión directa a `async def`; sus 870 ms de CPU bloquearían el event loop.
`POST /imports` se trata como carga mixta: el webhook puede ceder, pero los 312 ms de parseo siguen consumiendo CPU.
La conclusión no promete una mejora exacta sin una prueba de carga posterior.

Evidencia, revisión y reinicio

Revisión técnica guardada localmente en el navegador.
Recomendaciones vinculadas a mediciones del perfil.

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 perfil sin anotaciones.

Material descargable opcional

Perfil de endpointsMediciones por endpoint y plantilla breve de revisión.

Teoría que puedes consultar

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é 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.

Trabajo en el workspace

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.

Entrega esperada

Informe de compatibilidad línea por línea.
Resumen ejecutivo con riesgos y transición recomendada.

Tu razonamiento

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.

Material descargable opcional

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.

Teoría que puedes consultar

Unidad 1.2 · El contrato como límite

Series

Prácticas extendidas y opcionales. Cada serie conserva una base común y una parte utiliza el resultado de la anterior.

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.
La captura contiene una petición completa y una respuesta HTTP.
El contrato declara un media type específico para la creación.
Cada conclusión debe enlazarse con una evidencia del paquete.

Paquete de trabajo

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.

Cuaderno de la serie con hechos, hipótesis y decisiones.
Comando de reproducción, diagnóstico y propuesta contractual.

Revisión: con Codex, utilizando los artefactos y criterios de cada parte; no se publica una solución oficial.

Reinicio: Crear un directorio de trabajo nuevo y volver a descargar el ticket, el contrato y el cuaderno originales.

Parte 1 · Apoyo alto

EX-B1-S01-01 · Preparar la reproducción mínima

Convertir el tráfico capturado en una reproducción mínima que otro equipo pueda ejecutar sin reinterpretar el ticket.

Qué debes hacer

Escribe un comando `curl` con el método, URL, `Content-Type`, `Accept` y body observados.
Mantén el media type defectuoso: esta parte reproduce el incidente, todavía no lo corrige.
Resume en tres líneas el resultado esperado por el cliente, el status observado y el request ID.
No incluyas el token redactado ni inventes credenciales.

Entrega esperada

Comando de reproducción.
Resumen esperado/observado 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

Comando `curl` que reproduce el fallo observado.
Resumen de esperado, observado y evidencia de correlación.

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

Determinar si el problema pertenece al transporte, HTTP, JSON o contrato y descartar causas plausibles.

Qué debes hacer

Formula una hipótesis principal y al menos dos alternativas.
Comprueba cada hipótesis contra ticket, tráfico y OpenAPI.
Clasifica la capa en la que aparece la discrepancia.
Explica por qué dos causas plausibles no encajan con la evidencia.

Entrega esperada

Diagnóstico principal con nivel de confianza.
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

Diagnóstico principal con nivel de confianza.
Dos hipótesis descartadas mediante evidencia.

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

Rediseñar el comportamiento observable y explicar una transición compatible.

Qué debes hacer

Decide si debe cambiar el cliente, el contrato, el servidor o una combinación.
Describe el comportamiento corregido para éxito y error.
Propón una transición que contemple consumidores existentes.
Define criterios que permitirían verificar el cambio sin conocer la implementación.

Entrega esperada

Contrato corregido a nivel de diseño.
Nota de compatibilidad y transición.
Criterios observables de verificación.

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

Contrato corregido a nivel de diseño.
Nota de compatibilidad y criterios observables de verificació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.

Teoría que puedes consultar

Abrir práctica extendida: base común y 3 partes

Base común

La muestra contiene municipios, periodos e indicadores con unidades diferentes.
Los consumidores necesitan consultas filtradas y una exportación.
La colección debe paginarse y rechazar límites desproporcionados.
No se consumirá todavía una API pública ni se implementará FastAPI.

Paquete de trabajo

Muestra de indicadoresDataset sintético pequeño con dos indicadores, tres municipios y valores ausentes.
Necesidad y restriccionesDestinatarios, consultas necesarias, paginación y decisiones abiertas.
Plantilla OpenAPIEsqueleto deliberadamente incompleto para la tercera parte.

Entorno, evidencia y reinicio

Entorno: Dataset y plantillas descargables trabajados en un directorio separado del repositorio.

Inventario de recursos y representaciones.
Tabla de operaciones y documento OpenAPI acotado y autocontenido.

Revisión: con Codex, utilizando los artefactos y criterios de cada parte; no se publica una solución oficial.

Reinicio: Crear un directorio nuevo y volver a descargar la muestra, el brief y la plantilla OpenAPI originales.

Parte 1 · Apoyo moderado

EX-B1-S02-01 · Del dato al recurso

Identificar recursos, representaciones e identificadores a partir de la muestra.

Qué debes hacer

Distingue entidades con identidad de valores observados y catálogos.
Propón una representación JSON para una observación y otra para una colección.
Registra cómo representarás un valor ausente sin inventarlo.
Describe dos relaciones entre los recursos propuestos.

Entrega esperada

Inventario de recursos e identificadores.
Dos representaciones JSON conceptuales.

Criterios de aceptación

La interfaz no se modela como una lista de verbos.
Municipio, indicador, periodo, valor y unidad no se confunden.
El valor ausente conserva su significado.

Evidencia para revisión

Inventario de recursos e identificadores.
Dos representaciones JSON conceptuales.

Reinicio de esta parte: Reiniciar desde copias nuevas del dataset y del brief y conservar el resultado como checkpoint.

Pista · Busca identidad y estabilidad

Un nombre visible puede cambiar; revisa qué códigos de la muestra pueden funcionar como identificadores.

Parte 2 · Apoyo moderado

EX-B1-S02-02 · Rutas, filtros y errores

Diseñar operaciones de consulta y exportación sobre el modelo de recursos anterior.

Qué debes hacer

Define rutas y métodos para consultar colecciones y elementos.
Asigna filtros a path o query y justifica la elección.
Diseña paginación y un límite máximo observable.
Selecciona estados para recurso ausente, filtro inválido y solicitud demasiado amplia.
Decide cómo expresar la exportación sin introducir procesamiento asíncrono implementado.

Entrega esperada

Tabla de operaciones y parámetros.
Matriz de estados y condiciones.

Criterios de aceptación

Los filtros opcionales no se convierten arbitrariamente en segmentos de ruta.
La paginación tiene comportamiento y límites explícitos.
Los errores permiten al consumidor corregir la petición.

Evidencia para revisión

Tabla de operaciones y parámetros.
Matriz de estados y condiciones.

Reinicio de esta parte: Volver al checkpoint de la parte 1 o reconstruirlo desde una copia limpia de los materiales.

Pista · La ruta identifica; la query modifica la consulta

Utiliza esta regla como punto de partida y registra cualquier excepción.

Parte 3 · Apoyo ligero

EX-B1-S02-03 · Esqueleto de contrato OpenAPI

Trasladar el diseño a un contrato que un consumidor pueda leer y convertir en casos de prueba.

Qué debes hacer

Completa paths, parameters y responses del esqueleto proporcionado.
Define schemas reutilizables para observación, colección paginada y error.
Incluye ejemplos mínimos coherentes con la muestra.
Revisa required, tipos, formatos y referencias.

Entrega esperada

Documento OpenAPI legible, autocontenido y estructuralmente válido.
Tres casos de prueba descritos en lenguaje natural a partir del contrato.

Criterios de aceptación

Un consumidor puede formular una petición válida sin información externa.
Las respuestas satisfactoria y de error tienen schemas identificables.
Los ejemplos no contradicen tipos ni campos requeridos.

Evidencia para revisión

Documento OpenAPI legible, autocontenido y estructuralmente válido.
Tres casos de prueba descritos a partir del contrato.

Reinicio de esta parte: Volver al checkpoint de la parte 2 y descargar una plantilla OpenAPI sin completar.

Pista · Contrato antes que decoración

Prioriza operaciones, parámetros, schemas y respuestas; no necesitas completar todos los campos opcionales de OpenAPI.

Teoría que puedes consultar

Caso profesional extenso

CASE-B1 · Práctica extendida

¿Está lista esta integración?

Una organización quiere intercambiar expedientes con un proveedor, pero requisitos, tráfico y OpenAPI no describen el mismo comportamiento. Debes identificar los bloqueos que impiden empezar y proponer el contrato mínimo que permitiría una prueba de integración.

Abrir el encargo completo

Pregunta central

Información que necesitas

Para ordenar tu razonamiento

Trabajo en el workspace

Entrega esperada

Pistas opcionales

Contexto adicional

Cómo revisar tu respuesta

Evidencia, revisión y reinicio

Material descargable opcional

Teoría que puedes consultar

Pregunta central

Información que necesitas

Para ordenar tu razonamiento

Trabajo en el workspace

Entrega esperada

Selecciona tus respuestas

Pistas opcionales

Contexto adicional

Cómo revisar tu respuesta

Evidencia, revisión y reinicio

Material descargable opcional

Teoría que puedes consultar

Pregunta central

Para ordenar tu razonamiento

Trabajo en el workspace

Entrega esperada

Pistas opcionales

Contexto adicional

Decisiones abiertas

Cómo revisar tu respuesta

Evidencia, revisión y reinicio

Material descargable opcional

Teoría que puedes consultar

Pregunta central

Información que necesitas

Para ordenar tu razonamiento

Trabajo en el workspace

Entrega esperada

Selecciona tus respuestas

Pistas opcionales

Contexto adicional

Cómo revisar tu respuesta

Evidencia, revisión y reinicio

Material descargable opcional

Teoría que puedes consultar

Pregunta central

Documento OpenAPI

Para ordenar tu razonamiento

Trabajo en el workspace

Entrega esperada

Pistas opcionales

Contexto adicional

Cómo revisar tu respuesta

Evidencia, revisión y reinicio

Material descargable opcional

Teoría que puedes consultar

Pregunta central

Información que necesitas

Para ordenar tu razonamiento

Trabajo en el workspace

Entrega esperada

Selecciona tus respuestas

Pistas opcionales

Contexto adicional

Cómo revisar tu respuesta

Evidencia, revisión y reinicio

Material descargable opcional

Teoría que puedes consultar

Pregunta central

Información que necesitas

Para ordenar tu razonamiento

Trabajo en el workspace

Entrega esperada

Pistas opcionales

Contexto adicional

Cómo revisar tu respuesta

Evidencia, revisión y reinicio

Material descargable opcional

Teoría que puedes consultar