Cuando quieres pegar una respuesta de API en un README, una issue o una wiki interna, el JSON crudo es difícil de leer y lo que realmente quieres es una tabla Markdown. Esta guía recorre cómo llegar a esa tabla a partir de una respuesta de curl, incluyendo los casos que suelen complicarse: paginación, objetos anidados y respuestas que ni siquiera son un array.
El camino más corto es "curl al endpoint → recortar el array con jq → pasar por CSV → procesar con CSV a Markdown". Las respuestas que no son arrays se recortan hasta llegar al array que te interesa, o se envuelven en [ ... ] antes de convertir. Todo corre en el navegador, así que ni las cabeceras de autenticación ni los datos personales salen de tu máquina.
La respuesta corta: recorta el array y luego convierte
Que una respuesta JSON de API se vuelva una tabla Markdown depende de una sola pregunta: ¿puedes recortarla hasta dejar un array de objetos con la misma forma? La mayoría de APIs reales devuelven algo así, que por sí mismo no es una tabla.
{
"data": [
{ "id": "usr_001", "email": "mika@example.com", "active": true },
{ "id": "usr_002", "email": "noah@example.com", "active": false }
],
"pagination": { "page": 1, "total": 2 }
}
Lo que quieres como tabla es data. Baja primero a ese array y luego pásalo a CSV; el resultado es una tabla Markdown con encabezados y filas limpios.
El flujo: curl + jq + FormatArc
Aquí está toda la cadena en una secuencia de comandos. Está pensada para que puedas mirar la salida entre pasos, en vez de confiar en una sola caja negra.
# 1. Llamar a la API y guardar el JSON
curl -s -H "Authorization: Bearer $TOKEN" \
https://api.example.com/v1/users > users.json
# 2. Pegarlo en el Formateador JSON para confirmar la estructura
# https://formatarc.com/es/json-formatter/
# 3. Recortar el array data y construir un CSV
jq -r '.data | (map(keys) | add | unique) as $cols
| $cols, (.[] | [.[$cols[]]]) | @csv' users.json
# 4. Pegar el CSV en CSV a Markdown para obtener la tabla
# https://formatarc.com/es/csv-to-markdown/
Si necesitas afinar el propio curl o hacer legible la respuesta cruda, Cómo formatear JSON con curl cubre cuatro formas de hacerlo. Si prefieres saltar jq, puedes empezar pegando la respuesta en Formateador JSON y darle forma desde ahí.
Paso 1: obtener la respuesta y formatearla
Para un endpoint GET al que puedas llegar desde el navegador, copia la respuesta directamente a Formateador JSON. Con curl, -s silencia la barra de progreso y -H lleva la cabecera de autenticación.
Guardar la respuesta en un archivo es lo que facilita el resto del proceso, porque puedes volver a correr jq tantas veces como necesites.
curl -s -H "Authorization: Bearer $TOKEN" \
https://api.example.com/v1/users > users.json
cat users.json | python3 -m json.tool | head
python3 -m json.tool es el formateador de mínima dependencia para entornos sin jq. Para el set completo de one-liners, revisa la guía de formateo de JSON con curl.
Paso 2: recortar el array y construir el CSV
Mira el JSON formateado y localiza "qué clave guarda el array de objetos con la misma forma". Las formas más comunes son estas.
| Forma de la respuesta de API | Array que quieres | Recorte con jq |
|---|---|---|
[ {...}, {...} ] (array en la raíz) |
raíz | . |
{ "data": [ ... ] } |
data |
.data |
{ "items": [ ... ], "next": "..." } |
items |
.items |
{ "results": { "users": [ ... ] } } |
results.users |
.results.users |
Elige el recorte correcto y construye un CSV desde ahí.
jq -r '.data | (map(keys) | add | unique) as $cols
| $cols, (.[] | [.[$cols[]]]) | @csv' users.json
Esta expresión jq recopila todas las claves que aparecen en el array, las usa como fila de encabezado y escribe los valores de cada objeto en el mismo orden. Los objetos a los que les falta una clave aparecen como celda vacía, sin error de ejecución. @csv también maneja valores con comas o saltos de línea — los envuelve en "..." para que el CSV se pegue limpio en CSV a Markdown sin romper columnas.
Paso 3: convertir el CSV en tabla Markdown
Pega el CSV en CSV a Markdown y ejecuta la conversión.
La salida es compatible con GFM (GitHub Flavored Markdown), así que entra directa en archivos README, issues de GitHub, documentos de Notion o entradas Markdown de Slack. Si después quieres retocar la tabla a mano, Sintaxis de tablas en Markdown cubre las reglas a nivel de spec.
Formas de respuesta clasificadas por dificultad de conversión
Cada API devuelve una forma distinta y la dificultad de convertirla en tabla Markdown sigue esa forma. Aquí tienes una matriz de dificultad contra la que puedes comparar tu endpoint.
| Estilo de API | Estructura de la respuesta | Dificultad | Qué hacer |
|---|---|---|---|
| Endpoint de lista simple | array plano [ { ... } ] |
Baja | Pasar . tal cual |
| Colección envuelta | { "data": [ { ... } ] } |
Baja | Recortar con .data |
| Cursor o página numerada | { "items": [ ... ], "next_cursor": "..." } |
Media | Unir páginas con jq antes de recortar |
| Campos anidados por fila | { "user": { "name": ... }, "stats": { ... } } |
Media | Aplanar con claves con punto |
| Respuesta GraphQL | { "data": { "users": { "edges": [ { "node": { ... } } ] } } } |
Alta | Sacar los nodos con .data.users.edges[].node |
| Array heterogéneo | [ { type: "A", ... }, { type: "B", ... } ] |
Alta | Separar por tipo antes de armar tablas |
La decisión es la misma en todos los casos: confirma que puedes recortar hasta un array de objetos con la misma forma. Si no puedes, vuelve a Formateador JSON y encuentra la ruta de clave que te lleva ahí.
Unir respuestas paginadas en una sola tabla
Las APIs con cursor o con número de página devuelven la misma forma de array en cada página. La opción --slurp (-s) de jq combina varios archivos JSON en un solo array, así el resto del pipeline sigue funcionando.
for page in 1 2 3; do
curl -s "https://api.example.com/v1/users?page=$page" > "page-$page.json"
done
jq -s '[.[] | .data[]]
| (map(keys) | add | unique) as $cols
| $cols, (.[] | [.[$cols[]]]) | @csv' page-*.json
-s envuelve el JSON de cada archivo en un array externo, y .[] | .data[] recorre el data de cada respuesta y concatena sus elementos. A partir de ahí, el mismo pipeline de jq construye un único CSV que pegas en CSV a Markdown.
Aplana los objetos anidados antes de convertir
Si tu respuesta trae un registro de usuario con una dirección anidada, dejarlo tal cual mete {...} en la celda, lo cual es ilegible. Aplánalo con claves con punto.
[
{
"id": "usr_001",
"name": "Mika",
"address": { "city": "Tokyo", "zip": "100-0001" }
}
]
jq -r '.[] | {id, name, "address.city": .address.city, "address.zip": .address.zip}
| [.id, .name, ."address.city", ."address.zip"]
| @csv' users.json
El CSV ahora tiene cuatro columnas: id, name, address.city, address.zip. Pégalo en CSV a Markdown y los campos anidados aterrizan en columnas propias. Para arrays anidados (tags: ["a", "b"]), juntarlos con join("|") deja cada fila en una sola línea.
Cuando quieres mantenerlo en el navegador
Las respuestas de API suelen llevar cabeceras de autenticación, datos de clientes o IDs internos, así que pegarlas en un convertidor de terceros es difícil de justificar. FormatArc ejecuta la conversión en el navegador y nunca envía la entrada a un servidor. El detalle del mecanismo, junto con una comparación con convertidores hospedados, está en ¿Son seguros los convertidores online para JSON sensible?.
Un flujo puramente en el navegador se ve así:
- En lugar de curl, copia la respuesta desde las DevTools (pestaña Network)
- Pégala en Formateador JSON y verifica la estructura
- Deja solo las claves que necesitas y reorganiza el array como CSV
- Lleva el CSV a CSV a Markdown para obtener la tabla
Para arrays pequeños, dar forma al CSV a mano es perfectamente viable incluso sin jq.
Tropiezos típicos
Estas son las situaciones que tienden a descarrilar el flujo.
- La respuesta es un único objeto, no un array: envuélvelo como
[ ... ]o pásalo a una tabla de dos columnas clave/valor. Cómo convertir JSON en una tabla Markdown cubre ambos casos - A algunos objetos les faltan claves: el patrón
add | uniquede jq detecta todas las claves que aparecen en cualquier objeto y las que faltan quedan como celdas vacías - Los valores contienen saltos de línea o pipes (
|):@csvlos entrecomilla del lado CSV, pero en el Markdown final los pipes todavía deben ser\|. Cómo arreglar una tabla Markdown rota repasa los escapes - Los IDs numéricos grandes pierden precisión: las APIs que devuelven IDs como números se recortan en JavaScript. Conviértelos con
tostringde jq para que el CSV los guarde como cadenas - Caracteres mal codificados: prueba
curl --compressed, o pasa el cuerpo poriconv -f UTF-8antes de pegarlo en el Formateador JSON
Guías de conversión relacionadas
- Cómo formatear JSON con curl — cuatro formas (jq, Python, FormatArc, navegador) de formatear la salida de curl
- Cómo convertir JSON en una tabla Markdown — conversión general de JSON a tabla, no específica de API
- Cómo convertir CSV en una tabla Markdown — por qué CSV es un buen formato intermedio
- Consejos para formatear JSON — ordenar claves y arreglar arrays para hacer legible la estructura