Documentación de la API de multas que se prueba en el navegador
Una referencia con botón de “probar” acorta el camino entre leer y llamar, siempre que el ejemplo salga del mismo documento que describe la operación y el destino por omisión no sea producción.
Marco FerreiroAutor en multas.arLa mayoría de las referencias de API se leen y después se transcriben. Entre el ejemplo de la página y la primera llamada real hay un paso de traducción —copiar una URL, armar la cabecera de autenticación, adivinar el nombre de un parámetro— y ahí aparecen los errores que consumen la primera tarde de una integración de flota.
Una documentación ejecutable saltea ese paso: cada operación tiene un formulario que emite la solicitud desde el navegador y muestra la respuesta tal como llegó, con estado, cabeceras y cuerpo. El lector deja de discutir con una descripción y discute con el servicio. La contracara es que una consola que contesta algo distinto de lo que contesta la API de infracciones hace más daño que una página estática: deja una certeza falsa.
El documento de descripción manda sobre la página
OpenAPI reúne en un mismo archivo las operaciones, los parámetros, los esquemas, la lista de servidores y los mecanismos de seguridad. Cuando la consola se genera a partir de ese documento, el ejemplo que se ejecuta y la definición que se publica no pueden separarse. Cuando el ejemplo se escribe aparte, la separación es cuestión de tiempo: un parámetro que cambió de nombre —dominio por patente— sigue funcionando en la descripción y falla en la práctica.
La lista de servidores merece atención propia: antes de apretar, el lector tiene que ver contra qué base sale la consulta de esa patente. Un selector con el ambiente de prueba elegido por omisión es preferible a una consola que apunta a producción sin decirlo.
Qué credencial viaja en ese botón
La clave de producción no entra en una página de documentación.
RFC 6750 define el envío del token en la cabecera Authorization con el esquema Bearer y desaconseja pasarlo como parámetro en la URL: advierte que esa dirección probablemente quede registrada, y que navegadores y servidores no siempre resguardan bien el historial y los registros donde termina. Una consola que arma la URL con la credencial adentro enseña lo que la especificación pide evitar.
El fragmento copiable tiene el mismo problema: termina pegado en un ticket o en un chat, así que debería mostrar un marcador en lugar del valor, aunque el botón use la clave real para la llamada.
Lo que viene precargado es lo que más se ejecuta
El formulario llega con una patente puesta, y es la que más se ejecuta: alguien abre la página, aprieta y mira. Qué hace ese clic lo decide la página, no el ambiente de atrás.
Para las URL de ejemplo —el destino de un webhook, un host de retorno— hay nombres apartados: RFC 2606 reserva los dominios de primer nivel .test, .example, .invalid y .localhost, y registra example.com, example.net y example.org como nombres de segundo nivel para ejemplos. Un dominio real precargado convierte a un tercero en receptor de tráfico ajeno.
Con patentes, CUIT y números de acta el criterio es el mismo: la consola debería traer puestos los identificadores sintéticos que el ambiente de prueba ya reconoce, como se detalla en cómo diseñar un sandbox sin datos reales.
Un error se prueba mejor de lo que se explica
La respuesta exitosa es la que menos enseña. Una consola útil permite provocar fallas a propósito: falta un parámetro, la credencial está revocada, la jurisdicción no existe, el ritmo excede la cuota.
RFC 9457 define un formato de detalles de problema con type, title, status, detail e instance, extensible con campos propios. Mostrar ese cuerpo tal como llega vale más que una tabla de códigos:
{
"type": "/errores/credencial-revocada",
"title": "Credencial revocada",
"status": 401,
"detail": "La clave usada en la consola fue dada de baja.",
"instance": "/consultas/qry_7f2"
}
La página también debería mostrar la línea de estado y las cabeceras, no sólo el cuerpo formateado: un Retry-After o un identificador de solicitud que no se ven ahí son una sesión de depuración más adelante. Sobre cada respuesta, sirve leer qué significa cada código de estado.
El navegador no es el cliente definitivo
Lo que sale de una página no es idéntico a lo que sale de un backend. El navegador aplica sus propias reglas de origen y puede rechazar la llamada antes de que el servicio la vea; una consola honesta distingue ese caso de un error de la API en lugar de mostrar los dos como “falló”.
La inversa también importa: que una operación funcione en la consola prueba el contrato, no la red del cliente.
Qué revisar antes de publicar una consola
- confirmá que el ejemplo que se ejecuta sale del mismo documento que describe la operación;
- verificá que el servidor de destino esté a la vista y que por omisión no sea producción;
- entrá con una credencial del ambiente de prueba y comprobá que no quede guardada al recargar;
- mirá el fragmento copiable: debería traer un marcador y no la clave;
- provocá al menos un error por operación y leé la respuesta entera.
Una referencia ejecutable no reemplaza leer el contrato ni prueba que la integración esté lista. Lo que hace es mover la primera sorpresa: de la primera consulta de una patente en producción a una página donde todavía no hay nada que romper.
Metodología
- Alcance
- Criterios de diseño de una referencia de API ejecutable desde el navegador: origen de los ejemplos, credenciales, valores por omisión, errores visibles y límites del cliente. No evalúa herramientas ni generadores de documentación concretos.
- Unidad de análisis
- Una operación documentada y la solicitud que la consola emite desde el navegador cuando el lector la ejecuta.
- Cobertura
- La especificación OpenAPI para la descripción de operaciones, servidores y esquemas de seguridad, y RFC vigentes sobre detalles de problema, uso de bearer tokens y nombres reservados para documentación.
Limitaciones
- No revisa la implementación de un generador de documentación en particular ni sus opciones de configuración.
- El comportamiento del navegador ante llamadas entre orígenes depende de la configuración del servicio y del cliente; hay que verificarlo en el entorno real.
- Que una operación responda bien en la consola no garantiza que la integración funcione desde la red del cliente.
Fuentes
- OpenAPI Specification version 3.1.2 — OpenAPI Initiative (consultada el )
- RFC 9457 — Problem Details for HTTP APIs — RFC Editor (consultada el )
- RFC 6750 Bearer Token Usage — RFC Editor (consultada el )
- Reserved Top Level DNS Names — RFC Editor (consultada el )
Preguntas frecuentes
¿Una consola en la documentación reemplaza al ambiente de prueba?
No. La consola es la forma de emitir la solicitud; el ambiente de prueba es lo que responde. Sin un entorno con datos sintéticos y errores reproducibles, el botón queda con dos destinos posibles: una respuesta simulada por la propia página, que no prueba el contrato, o producción.
¿Conviene dejar la clave de producción cargada en la consola?
No. RFC 6750 desaconseja llevar el token en la URL: advierte que es muy probable que esa dirección quede registrada, y que navegadores y servidores no siempre resguardan bien el historial y los registros donde queda. Una página pública suma lugares donde el valor se copia sin querer: capturas, fragmentos pegados en un ticket, un chat. Lo razonable es una credencial del ambiente de prueba, con alcance acotado, que no se persista más allá de la sesión.
¿Por qué una llamada funciona en la consola y falla desde mi servidor?
Porque no son el mismo cliente. El navegador aplica sus propias reglas de origen y la red de una empresa agrega proxies, inspección de TLS y listas de salida. Que la operación responda en la página prueba el contrato, no el camino que va a usar la integración.
¿Alcanza con mostrar el camino feliz en la documentación?
Es lo que menos enseña. Conviene que cada operación tenga al menos una falla reproducible a propósito y que la respuesta se muestre tal como llega, con estado y cabeceras, no sólo el cuerpo formateado.
Notas relacionadas
Cómo diseñar un sandbox de API útil sin usar patentes ni personas reales
Un entorno de prueba sirve cuando reproduce decisiones y fallas del contrato, no cuando copia expedientes de producción. Los escenarios deterministas hacen posible probar sin PII.
Tests de contrato de la API de multas: cambios incompatibles
Un campo opcional nuevo suele ser compatible; un enum cerrado nuevo puede romper un cliente estricto. Los fixtures de consumidor convierten esas diferencias en pruebas antes del despliegue.
Códigos de estado: qué significa cada uno en la práctica
Un 200 no dice que el vehículo esté sin deuda y un 404 no dice que el dominio no exista. El número califica la solicitud; el resultado de la consulta vive en el cuerpo.