Etiquetas

Las etiquetas (tags) son palabras clave transversales que puedes asignar a tus posts para clasificarlos de forma flexible. A diferencia de las categorías, las etiquetas no son jerárquicas — son una lista plana. Son perfectas para construir nubes de tags, páginas de etiqueta y sistemas de filtrado flexible que no encajan bien en una estructura de árbol.

GET /tags — Listado de etiquetas

Devuelve todas las etiquetas de la web en un array plano. Este endpoint no tiene paginación — siempre devuelve el listado completo, porque las etiquetas son datos ligeros y suele haber pocas decenas como máximo. El orden de la respuesta es alfabético por nombre.

curl "https://tu-panel.com/api/v1/tags?web_id=abc-123&lang=es" \
  -H "X-API-Key: tu-api-key"

const response = await fetch(
  'https://tu-panel.com/api/v1/tags?web_id=abc-123&lang=es',
  { headers: { 'X-API-Key': 'tu-api-key' } }
)
const { data } = await response.json()

{
  "data": [
    { "id": "tag-001", "nombre": "API REST", "slug": "api-rest" },
    { "id": "tag-002", "nombre": "Headless", "slug": "headless" },
    { "id": "tag-003", "nombre": "Astro", "slug": "astro" }
  ]
}

Campos de respuesta

Etiquetas vs categorías: cuándo usar cada una. Usa categorías cuando el contenido tiene una estructura temática clara y jerárquica — por ejemplo, "Tecnología > Frontend > CSS". Usa etiquetas para clasificaciones transversales que no encajan en esa jerarquía — por ejemplo, "tutorial", "opinión", "recurso", "video". Un post puede pertenecer a una sola categoría pero tener múltiples etiquetas. Las etiquetas también son útiles para agrupar una serie de artículos relacionados sin necesidad de crear una subcategoría nueva.

Para renderizar una nube de tags en tu frontend, llama a este endpoint y mapea el array. Puedes ordenar por nombre o asignar tamaños de fuente aleatorios si no tienes un campo de popularidad:

// Ejemplo: nube de tags con tamaños proporcionales (si tuvieras el count)
const { data: tags } = await fetch('/api/v1/tags?web_id=...').then(r => r.json())

// Renderizar en HTML (vanilla JS)
const cloud = tags.map(tag =>
  `<a href="/blog/tag/${tag.slug}" class="tag">${tag.nombre}</a>`
).join(' ')

document.getElementById('tag-cloud').innerHTML = cloud

Casos de uso

Nube de tags en el blog. Obtén todas las etiquetas y renderízalas como enlaces en el sidebar o en el pie de página del blog. Cada etiqueta enlaza a su página de listado filtrado.

Página /tag/[slug]. Genera una ruta estática por cada etiqueta y usa el parámetro tag del endpoint de posts para filtrar: /api/v1/posts?web_id=...&tag=headless. Combina ambas llamadas para tener el nombre de la etiqueta y sus posts.

Tags como "serie". Crea una etiqueta por serie de artículos — por ejemplo, "serie-vue-3" — y asígnala a todos los posts de esa serie. Así puedes mostrar fácilmente todos los posts de la serie en cualquier página usando el filtro tag.

Filtros dinámicos en el cliente. Carga todos los posts y todas las etiquetas al inicio y filtra en el cliente sin peticiones adicionales. Esta estrategia funciona bien con colecciones pequeñas (menos de 200 posts) y evita tiempos de carga en cada cambio de filtro.

Consejos y buenas prácticas

• No crees demasiadas etiquetas. Una nube de 100 tags es difícil de navegar y pierde utilidad. Intenta mantener las etiquetas por debajo de 30-40 para que la navegación sea significativa.
• Usa slugs en minúsculas y consistentes. Si tienes "api-rest" y "API REST" como etiquetas distintas estarás dividiendo el contenido innecesariamente. Gestiona las etiquetas desde el panel con criterio editorial.
• Cachea este endpoint con un TTL largo — las etiquetas cambian raramente. Invalidar la caché al publicar un nuevo post con etiquetas nuevas es suficiente.
• Las etiquetas no tienen descripción ni imagen. Si necesitas enriquecer las páginas de etiqueta con texto introductorio, guarda ese contenido en tu propio frontend o usa una categoría con descripción.

Errores frecuentes

Ver también

• Posts — filtra posts por etiqueta con el parámetro tag
• Categorías — organización jerárquica del contenido