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.
Qué cubre y qué no
Sección titulada «Qué cubre y qué no»| 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 |
Una ruta que pide sesión
Sección titulada «Una ruta que pide sesión»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 unUnauthorizedError.forUser(locals.cms, user)es la API local actuando como esa persona: lo queaccessle 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 contesta401con{ "error": "UNAUTHORIZED", "message": "…" }.
Una ruta en el ámbito de una colección
Sección titulada «Una ruta en el ámbito de una colección»Un fichero con el nombre de la colección en la carpeta, y [id] donde va el documento:
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.
Una ruta pública
Sección titulada «Una ruta pública»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)}Qué responde cuando falla
Sección titulada «Qué responde cuando falla»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.
Lo que tapas
Sección titulada «Lo que tapas»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.
Lo que no heredas
Sección titulada «Lo que no heredas»- El
405. Un verbo que no exportas lo contesta Astro con un404sin cuerpo; el CMS contesta un405con su JSON antes de mirar la sesión. Si lo quieres, exportaALLy lanzanew MethodNotAllowedError(…)porerrorResponse. - El CORS. Las rutas del CMS responden con la lista de
corsde la integración; la tuya no manda ninguna cabeceraAccess-Control-*. Si la llaman desde otro origen, las pones tú con el segundo argumento deerrorResponsey en tus respuestas. api.path. La URL de una ruta de Astro es la de su fichero. Si cambiasapi.path, las tuyas se quedan donde estaban.