Ir al contenido

Rutas propias

Kevin CMS no tiene una opción endpoints en el config: las rutas de la API REST son las que son. Para una ruta tuya —publicar un borrador, unas estadísticas, un webhook— usas lo que ya tienes, una ruta de Astro en src/pages/api/ que lee Astro.locals.cms, el mismo objeto que usan tus páginas. Esta guía es la receta, y lo que esa receta no te da.

Con una ruta de Astro
Ruta de raíz, /api/estadisticas Sí
Ámbito de una colección, /api/cms/posts/:id/publicar Sí: un fichero bajo src/pages/api/cms/posts/
Ámbito de un global, /api/cms/globals/site/vista-previa Sí: un fichero bajo src/pages/api/cms/globals/site/
Actuar como la persona de la sesión Sí, con forUser
Que defineConfig rechace una ruta que tape una incorporada No. Ver lo que tapas
Cerrada por defecto No: es pública hasta que pides sesión
El 405 y el CORS del CMS No. Ver lo que no heredas
Seguir a api.path No: la URL es la del fichero
Rutas aportadas por plugins No: Kevin CMS no tiene plugins
src/pages/api/estadisticas.ts
import type { APIRoute } from 'astro'
import { errorResponse, forUser } from '@kevolution-co/cms'
export const prerender = false
export const GET: APIRoute = async ({ locals }) => {
try {
const user = await locals.cms.auth.requireUser()
const cms = forUser(locals.cms, user)
return Response.json({
publicados: await cms.collections.posts.count({ where: { status: { equals: 'published' } } }),
})
} catch (error) {
return errorResponse(error)
}
}
  • requireUser() devuelve a la persona de la sesión, o lanza un UnauthorizedError.
  • forUser(locals.cms, user) es la API local actuando como esa persona: lo que access le deja leer o escribir es lo que la ruta puede hacer, sin repetir { user } en cada llamada.
  • errorResponse(error) convierte lo que se lance en la respuesta que daría la API REST. Sin sesión, esta ruta contesta 401 con { "error": "UNAUTHORIZED", "message": "…" }.

Un fichero con el nombre de la colección en la carpeta, y [id] donde va el documento:

src/pages/api/cms/posts/[id]/publicar.ts
import type { APIRoute } from 'astro'
import { errorResponse, ForbiddenError } from '@kevolution-co/cms'
export const prerender = false
export const POST: APIRoute = async ({ locals, params }) => {
try {
const user = await locals.cms.auth.requireUser()
if (user.role !== 'admin') throw new ForbiddenError('Solo una cuenta admin publica')
const post = await locals.cms.collections.posts.update(
params.id as string,
{ status: 'published' },
{ user },
)
return Response.json(post)
} catch (error) {
return errorResponse(error)
}
}

access.admin solo gobierna el panel y /settings: una ruta tuya no lo comprueba. Si debe ser solo para administradores, la comprobación del role la escribes tú, como arriba. Aun sin ella, el update pasa por el access.update de la colección, porque la llamada lleva { user }: es lo mismo que forUser hace por ti en cada llamada. Un id que no existe es un 404 y un cuerpo inválido un 400 con issues, como en la REST.

src/pages/api/destacados.ts
import type { APIRoute } from 'astro'
import { forUser } from '@kevolution-co/cms'
export const prerender = false
export const GET: APIRoute = async ({ locals }) => {
// `null` para un visitante: cada lectura sigue lo que `access.read` le deja ver.
const user = await locals.cms.auth.getUser()
const cms = forUser(locals.cms, user)
const { docs } = await cms.collections.posts.find({ where: { featured: { equals: true } } })
return Response.json(docs)
}

requireUser(), la API local y tus propios throw lanzan errores del CMS. Solo la API REST los traduce; en una ruta tuya, sin un try/catch, Astro contesta un 500. errorResponse(error), exportada de @kevolution-co/cms, hace la traducción de la REST:

Se lanza Sale
UnauthorizedError (requireUser(), o access que niega a un visitante) 401
ForbiddenError (access que niega a una sesión) 403
NotFoundError (un id que no existe, o que access esconde) 404
ValidationError 400, con issues
Cualquier otro CMSError de menos de 500 su status
Cualquier otra cosa 500 con INTERNAL_ERROR; el original va a los logs, no al cliente

El cuerpo es { "error": código, "message": texto }. Un segundo argumento, errorResponse(error, headers), añade cabeceras a la respuesta —por ejemplo las de tu CORS—.

En una página .astro no hace falta: ahí getUser() y Astro.redirect son lo habitual. Ver Autenticación.

Medido en astro dev, con estos ficheros bajo src/pages/api/cms/ en la demo:

Tu fichero Lo que dejó de funcionar
posts/count.ts GET /api/cms/posts/count, y el 405 de los demás verbos sobre esa ruta
settings.ts Los ajustes: GET y PATCH /api/cms/settings
authors/[id].ts Leer, editar y borrar un documento de authors
posts/featured.ts Nada: featured no es una ruta incorporada, solo un id que ningún documento tiene
posts/[id]/publicar.ts Nada: las incorporadas no tienen tres segmentos

Lo que el CMS sirve bajo api.path y por tanto no debes pisar:

  • /<colección> y /<colección>/count, /<colección>/upload, /<colección>/<id>
  • /globals/<slug>
  • /settings
  • /cdn/<colección>/<id> y /cdn/<colección>/<id>/<nombre>

Lo más simple es no poner tus rutas bajo api.path: una carpeta propia como src/pages/api/app/ no puede tapar nada. Si las pones ahí, que el primer segmento no sea una colección, globals, settings ni cdn, y que bajo una colección el nombre no sea count ni upload ni un [id] suelto.

  • El 405. Un verbo que no exportas lo contesta Astro con un 404 sin cuerpo; el CMS contesta un 405 con su JSON antes de mirar la sesión. Si lo quieres, exporta ALL y lanza new MethodNotAllowedError(…) por errorResponse.
  • El CORS. Las rutas del CMS responden con la lista de cors de la integración; la tuya no manda ninguna cabecera Access-Control-*. Si la llaman desde otro origen, las pones tú con el segundo argumento de errorResponse y en tus respuestas.
  • api.path. La URL de una ruta de Astro es la de su fichero. Si cambias api.path, las tuyas se quedan donde estaban.