Endpoints que emiten JSON y otros formatos

Un feed y un sitemap son casos concretos de una idea general: una URL puede devolver cualquier cosa, no solo HTML. Cuando exportas una función GET en un fichero .ts bajo src/pages y devuelves un Response, has construido una API sin backend separado: un endpoint que sirve JSON, texto o CSV derivado de tu contenido. La misma getCollection que pinta las páginas alimenta ahora a consumidores que no son navegadores —un script, otra app, una hoja de cálculo—. Tu sitio deja de ser solo algo que se mira y pasa a ser algo que se consulta.

Un GET que devuelve JSON

Un endpoint de datos es un fichero cuyo nombre incrusta el formato de salida. src/pages/api/posts.json.ts se sirve en /api/posts.json: la primera extensión forma parte de la URL, la segunda solo le dice a Astro que es un endpoint. Dentro exportas una constante GET tipada como APIRoute y devuelves un Response. Para JSON, el método estático Response.json de la plataforma web fija la cabecera Content-Type por ti.

// src/pages/api/posts.json.ts
import type { APIRoute } from 'astro';
import { getCollection } from 'astro:content';

export const GET: APIRoute = async () => {
  const posts = await getCollection('blog', ({ data }) => !data.draft);
  const datos = posts.map((post) => ({
    id: post.id,
    title: post.data.title,
    date: post.data.pubDate,
  }));
  return Response.json(datos);
};

Fíjate en el map: el endpoint no vuelca la entrada entera, sino que elige qué campos expone. Eso importa, porque un endpoint público es un contrato con quien lo consuma y una superficie por la que puede filtrarse información. Decidir la forma de la salida —qué campos, con qué nombres— es diseñar esa API, no un detalle accesorio.

Derivar el contenido: elegir la forma pública

El endpoint es una vista de la colección, igual que una página, pero cuya plantilla decides byte a byte. Filtras borradores, seleccionas campos, renombras claves y ordenas para el consumidor. Como es estático por defecto, la respuesta se hornea a un fichero en el build; si lo sirves bajo demanda, una cabecera Cache-Control gobierna cuánto puede guardarse en caché. Construir el Response a mano te da control total sobre el estado y las cabeceras.

export const GET: APIRoute = async () => {
  const posts = await getCollection('blog');
  const datos = posts.map((post) => ({ id: post.id, title: post.data.title }));
  return new Response(JSON.stringify(datos), {
    headers: {
      'Content-Type': 'application/json; charset=utf-8',
      'Cache-Control': 'public, max-age=3600',
    },
  });
};

Construir el Response a mano también te da el código de estado, que es vocabulario para el consumidor automático. Un endpoint que no encuentra lo pedido devuelve un 404 con un cuerpo JSON que lo explica; uno que recibe una petición mal formada, un 400. Esos códigos los entiende un programa sin leer el cuerpo, y omitirlos —responder siempre 200 con el error escondido dentro— es una de las formas más comunes de API maleducada, la que obliga al cliente a adivinar si algo salió bien.

Un endpoint por entrada con getStaticPaths

Como las páginas, un endpoint puede ser dinámico. src/pages/api/[id].json.ts sirve un JSON por entrada, y en modo estático necesita getStaticPaths para enumerar qué ficheros generar —exactamente el mismo patrón que una ruta [slug].astro, solo que la salida es JSON en vez de HTML—. En SSR, en cambio, el endpoint lee params en cada petición y no necesita enumerar nada por adelantado.

// src/pages/api/[id].json.ts
import type { APIRoute, GetStaticPaths } from 'astro';
import { getCollection } from 'astro:content';

export const getStaticPaths: GetStaticPaths = async () => {
  const posts = await getCollection('blog');
  return posts.map((post) => ({
    params: { id: post.id },
    props: { post },
  }));
};

export const GET: APIRoute = ({ props }) => {
  return Response.json(props.post.data);
};

El paralelismo con las páginas es total: getStaticPaths recorre la colección y emite una ruta por entrada, y cada ruta —sea página o endpoint— recibe su entrada como prop. Cambia el tipo de salida, no el mecanismo de enrutado. Aprendido para páginas, se reutiliza tal cual para APIs.

En SSR ese mismo endpoint dinámico no necesita getStaticPaths: lee params.id de la petición y consulta la entrada en el momento, igual que una página bajo demanda. Y si un recurso debe responder a varios verbos con la misma lógica, ALL los atiende todos con una sola función, cómodo cuando lo que importa es la ruta y no el método concreto que la invoca.

Otros formatos

El mismo molde sirve cualquier tipo MIME: cambias la cabecera Content-Type y el cuerpo. Un CSV para exportar a una hoja de cálculo, texto plano, un .ics de calendario, incluso una imagen generada. La extensión del nombre construye la URL, y la cabecera le dice al cliente cómo interpretar los bytes.

// src/pages/posts.csv.ts  ->  /posts.csv
export const GET: APIRoute = async () => {
  const posts = await getCollection('blog');
  const filas = posts.map((p) => `${p.id},${p.data.title}`).join('\n');
  return new Response(`id,title\n${filas}`, {
    headers: { 'Content-Type': 'text/csv; charset=utf-8' },
  });
};

flowchart LR
GC[getCollection blog] --> SHAPE[elegir campos y forma]
SHAPE --> RES[Response con Content Type]
RES --> J[salida JSON]
RES --> C[salida CSV]
RES --> T[salida texto]
style GC fill:#89b4fa,color:#11111b
style J fill:#a6e3a1,color:#11111b
style C fill:#a6e3a1,color:#11111b
style T fill:#a6e3a1,color:#11111b