Práctica extendida · Bloque 1
EX-B1-S02
Contrato de consulta de datos públicos
Un equipo de análisis quiere consultar indicadores municipales desde una API interna. Solo existe una pequeña muestra tabular y varias restricciones de consumo.
Cómo abordarla
Diseño progresivo sobre una evidencia común
Trabaja las partes sobre la misma base y conserva un checkpoint verificable después de cada transformación.
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.