Distinguir descripción y aplicación
Fije una versión compatible con sus herramientas. Describa parámetros, cuerpos, respuestas y requisitos de seguridad. Declarar estos requisitos no sustituye su aplicación en servidor y pasarela.
| Elemento | Qué describe | Verificación adicional |
|---|---|---|
| Esquema | Estructura y restricciones | Validación real y reglas de negocio. |
| Respuesta documentada | Estado y contenido esperados | Conformidad de respuestas reales. |
| Requisito de seguridad | Mecanismo y permisos declarados | Control efectivo por operación. |
| Ejemplo | Un caso ilustrativo | Coherencia, ausencia de secretos y casos límite. |
Revisar antes de compartir
- Compruebe campos obligatorios, tipos, intervalos, paginación, errores y formatos. Use ejemplos ficticios coherentes, sin secretos ni datos de clientes.
- Compare el documento con solicitudes y respuestas en un entorno controlado. Pruebe ausencia de credenciales, permisos insuficientes y separación de cuentas.
- Revise referencias externas y las herramientas que las resuelven. Expurgue la descripción pública y proteja entornos y operaciones privados.
Mantener la documentación
Revise cambios y asigne un responsable. Un cliente generado o ejemplo puede cumplir la estructura e ignorar una regla de negocio. Las consolas interactivas necesitan entorno adecuado, permisos limitados y operaciones modificadoras claramente señaladas.
Fuentes primarias
Compare OpenAPI con el servicio en ejecución.
Una descripción útil de OpenAPI incluye respuestas de error, esquemas y ejemplos que los clientes encuentran en la práctica. Cuando el documento y la API difieren, una integración puede superar una demostración y fallar en producción.
- Compare los casos de éxito y error con la descripción.
- Documente los valores opcionales, la paginación y los límites de operación.
- Pruebe con un cliente representativo antes de modificar el contrato.
Fuente primaria: IETF RFC 9457 — Problem Details for HTTP APIs. Método relacionado: consultar la guía práctica.
Archivos ZIP y TAR: extraer con límites de ruta y recursos
Validar rutas, enlaces y datos descomprimidos antes de publicar los archivos obtenidos.
- Extrae en un directorio nuevo no público con permisos mínimos. Rechaza rutas absolutas, recorrido ascendente, enlaces y archivos especiales innecesarios. Comprueba destinos resueltos y colisiones según el sistema, incluida la distinción de mayúsculas. Un prefijo textual no prueba confinamiento.
- Fija límites por archivo y totales de bytes escritos, entradas, profundidad, tiempo y recursos. No dependas solo del tamaño comprimido o declarado. Rechaza archivos anidados innecesarios; si se permiten, comparte un presupuesto global. Mantén biblioteca y filtros actualizados.
- Prueba ../, ruta absoluta, enlace, duplicado y exceso de presupuesto. Un fallo debe dejar el lote sin publicar y sin reemplazar archivos existentes. Valida tipos y contenido antes de promover; limpia el directorio con una operación que compruebe su destino.
Caso de aceptación reproducible
Ejemplo ficticio: estos datos no describen clientes ni resultados observados.
Ver datos del caso
{
"compressed_mb": 2,
"expanded_mb": 600,
"aggregate_budget_mb": 100,
"first_files_valid": true,
"expected": "stop_on_actual_overrun_and_do_not_promote"
}Decisión esperada
Ejemplo ficticio: un ZIP de 2 MB produce 600 MB con presupuesto de 100 MB. Detén al superar los bytes escritos y no publiques el lote aunque los primeros archivos parezcan válidos.
Python — tarfile extraction filters and further verification
¿Un archivo pequeño o un filtro garantiza seguridad?
No. Puede expandirse mucho. Añade límites de recursos, reglas de rutas y validación del resultado.
Fuente primaria: Python — tarfile extraction filters and further verification. Método relacionado: consultar la guía práctica.
Errores API: tipos, estados y pruebas
Las notas detalladas de esta edición están disponibles en inglés.
Include errors in contract tests
A new type URI, removed extension or changed status may alter consumer behaviour. Failure examples are part of the contract alongside successful responses.
- Replay existing clients against representative refusals.
- Check tolerance of unknown extensions and localised text.
- Document migration of a problem identity and actually observed use.
Explore problem types and eight fictional responses →
IETF · M. Nottingham, E. Wilde, S. Dalal · RFC 9457 · July 2023 · obsoletes RFC 7807 · §3.1, §3.2, §4.2, §5