API de entrega headless
Esta es una referencia para desarrolladores. Si estás configurando un espacio headless por primera vez, comienza con Crear un espacio headless.
Cada espacio headless sirve sus entradas publicadas desde una API de lectura pública, cacheable en CDN. No requiere autenticación ni clave de API — la API devuelve solo entradas publicadas (los borradores y las entradas programadas nunca aparecen), y un blog es público por definición.
La URL base de tu espacio — incluidos los identificadores de workspace y sitio — se muestra en la página Delivery API del sitio en el portal de cliente, junto con URLs de feed listas para usar por idioma. Todas las rutas que se indican a continuación son relativas a esa base.
Endpoints
| Ruta | Devuelve |
|---|---|
GET /posts | Entradas publicadas, las más recientes primero (solo campos de resumen) |
GET /posts/{slug} | Una entrada publicada, contrato completo (ver más abajo) |
GET /terms | Categorías y etiquetas con recuento de entradas |
Parámetros de consulta (/posts)
| Parámetro | Descripción |
|---|---|
language | Entradas en un idioma (p. ej. de). Cada idioma es un blog separado — una campaña por idioma. |
category | Filtrar por slug de categoría. Mutuamente exclusivo con tag. |
tag | Filtrar por slug de etiqueta. Mutuamente exclusivo con category. |
cursor | Página siguiente (más antigua) — pasa el nextCursor de la respuesta anterior. |
before | Página anterior (más reciente) — pasa el prevCursor de la respuesta. |
limit | Elementos por página; valor predeterminado y máximo 50. |
language se combina con category o tag:
/posts?language=de&category=news es el archivo “News” del blog en alemán.
/terms?language=de aplica el mismo ámbito a la taxonomía.
Paginación
Las respuestas de lista son bidireccionales: cada una devuelve nextCursor
(hacia entradas más antiguas) y prevCursor (hacia entradas más recientes).
Un cursor null significa que no hay más páginas en esa dirección — renderiza
cada página únicamente a partir de su token de URL, sin necesidad de mantener
un historial de cursores.
Contrato de respuesta de entrada individual
GET /posts/{slug} devuelve { post } con:
id,slug,title,excerpt— identidad y texto de resumen.html— el contenido renderizado y saneado. Los enlaces relativos a la raíz se convierten en absolutos tomando como referencia la URL pública de tu sitio. Se puede inyectar tal cual: lista de etiquetas permitidas estricta, sin atributos<script>/<style>/on*.blocks— el array de bloques estructurado, si prefieres renderizar en lugar de inyectarhtml.metaTitle,metaDescription,keyphrase,categories,tags.featuredImage,bodyImage—{ url, width, height, alt?, caption? }.og—{ title, description, image }, listo para etiquetas Open Graph.author—{ name, bio, avatarUrl, profileUrl, sameAs }, el autor real al que el sitio atribuye la entrada, onullsi el sitio no tiene un autor definido para la persona de la entrada. Nunca es el nombre de la persona (la voz de escritura).bio,avatarUrlyprofileUrlpueden sernull;sameAses un array con las URL de otros perfiles del autor y puede estar vacío. El autor se define por persona y por sitio en el portal de cliente; consulta ¿Qué es una persona?.schema— un array de objetos JSON-LD de schema.org. El primer elemento es unBlogPostingde la entrada:headline,description,image,@idymainEntityOfPagea partir de la URL canónica de la entrada,datePublished,dateModifiedy el autor comoPerson(name,description,image,url,sameAs). Los campos vacíos se omiten, y tambiénauthorcuando la entrada no tiene autor. No incluyepublisher: el nodo Organization lo aporta tu sitio. Después siguenHowToyFAQPagecuando la entrada contiene esas secciones. Se entrega fuera de banda porque el saneador del contenido elimina<script>— emite un<script type="application/ld+json">por entrada en el<head>de tu página para ser elegible para resultados enriquecidos. Las secciones correspondientes del contenido llevan las clasesstructura-howto/structura-faqpara el estilo.publishedAt,updatedAt— ISO 8601.updatedAtes tu señal de revalidación.
La respuesta de lista devuelve solo el subconjunto de resumen — sin html,
blocks, author ni schema.
Marcado de artículo y firma del autor
Si emites todos los elementos de schema, las páginas de tus entradas incluyen
marcado de artículo y de autor que los buscadores pueden usar para resultados
enriquecidos, sin trabajo adicional. Si tu sitio ya genera su propio nodo
Article o BlogPosting, deja fuera el nuestro; si no, cada página declara dos
artículos:
const jsonLd = post.schema.filter((entry) => entry["@type"] !== "BlogPosting");Después toma el autor para tu propio nodo de post.author.
Para mostrar la firma, usa post.author.name, la imagen de avatarUrl y la
bio, y enlaza el nombre a profileUrl cuando exista. Si post.author es
null, omite la firma.
Consumo desde un framework
Realiza la solicitud en el momento de la compilación o la revalidación y trata la API como tu CMS:
// Next.js App Router — a blog index with ISR
const BASE = process.env.STRUCTURA_DELIVERY_BASE; // from the Delivery API page
export default async function BlogIndex() {
const res = await fetch(`${BASE}/posts?language=en`, {
next: { revalidate: 300 },
});
const { posts } = await res.json();
// render titles/excerpts; link to /blog/[slug]
}// One post page — getStaticPaths-friendly
const res = await fetch(`${BASE}/posts/${slug}`);
const { post } = await res.json();
// inject post.html, emit post.schema entries as JSON-LD in <head>
// (filter out the BlogPosting entry if you build your own Article node),
// render a byline from post.author when it is not nullLas respuestas se almacenan en la caché de la CDN. Si consultas la API
periódicamente, vincula la revalidación a updatedAt en lugar de volver a
renderizar siempre.
Páginas relacionadas
- Crear un espacio headless
- API REST del plugin — el equivalente del lado de WordPress
Última verificación: