API REST
Las operaciones de la API local expuestas por HTTP. Esta capa no decide nada: traduce una petición a una llamada de la API local y su resultado a una respuesta. Todo lo que decide qué documentos salen o qué escrituras valen está documentado en la otra página.
La integración de Astro monta todas estas rutas por ti. La firma del final de la página solo importa si montas el CMS a mano.
Endpoints
Sección titulada «Endpoints»Prefijo por defecto /api/cms, configurable con api.path.
| Método | Ruta | Operación | Éxito |
|---|---|---|---|
GET |
/api/cms/:collection |
find |
200 |
POST |
/api/cms/:collection |
create |
201 |
GET |
/api/cms/:collection/count |
count |
200 |
GET |
/api/cms/:collection/:id |
findByID |
200 |
PATCH |
/api/cms/:collection/:id |
update |
200 |
DELETE |
/api/cms/:collection/:id |
delete |
200 |
count se resuelve antes que :id, así que nunca se interpreta como el id de un documento.
Las actualizaciones son PATCH y no PUT: son parciales, y PUT prometería un reemplazo total que no
ocurre. findOne no tiene endpoint —?limit=1 sobre el listado da lo mismo— y la autenticación se sirve
aparte, en /api/auth/*.
Escrituras condicionales
Sección titulada «Escrituras condicionales»Las respuestas de un documento único —GET /:id, POST y PATCH— llevan una cabecera ETag con el
updatedAt del documento entre comillas, el mismo valor que viaja en el cuerpo (salvo un GET /:id con
un ?select= que no pida updatedAt: sin ese campo no hay de dónde sacar la cabecera):
ETag: "2026-01-01T00:00:00.001Z"Un PATCH puede mandarlo de vuelta en If-Match para escribir solo si nadie ha tocado el documento
desde que lo leíste:
PATCH /api/cms/posts/01J8… HTTP/1.1If-Match: "2026-01-01T00:00:00.001Z"Content-Type: application/json
{ "title": "Hola de nuevo" }Si el updatedAt de la fila ya no coincide, la respuesta es 412 con código PRECONDITION_FAILED y no
se escribe nada: vuelve a leer el documento, aplica tu cambio sobre la copia nueva y reintenta con el
ETag que te devolvió. Sólo se compara un entity-tag fuerte, entre comillas dobles, contra el
updatedAt que el documento tiene ahora mismo: cualquier otra forma —la fecha sin comillas, *,
W/"…", una lista de varios tags o basura— nunca coincide y también es 412; un id que no existe
sigue siendo 404, se mande lo que se mande.
La cabecera es opcional: sin If-Match, PATCH escribe como siempre. Los listados, count,
DELETE, la subida de ficheros y las dos rutas de un global no llevan
ETag. Desde un navegador y otro origen también funciona, siempre que el origen esté
en la lista de CORS: el preflight autoriza If-Match y la respuesta expone ETag.
Ficheros
Sección titulada «Ficheros»Las colecciones que declaran upload añaden dos rutas más. Están documentadas en
Ficheros:
| Método | Ruta | Qué hace | Éxito |
|---|---|---|---|
POST |
/api/cms/:collection/upload |
Sube un fichero con multipart/form-data |
201 |
POST |
/api/cms/:collection/upload?action=create |
Abre una subida por trozos | 201 |
PUT |
/api/cms/:collection/upload?action=part |
Manda un trozo | 200 |
POST |
/api/cms/:collection/upload?action=complete |
Cierra la subida y crea el documento | 201 |
DELETE |
/api/cms/:collection/upload?action=abort |
Cancela la subida | 200 |
GET |
/api/cms/cdn/:collection/:id/:filename |
Devuelve el fichero | 200 |
GET |
/api/cms/cdn/:collection/:id |
Redirige a la ruta canónica | 302 |
upload se resuelve antes que :id, igual que count. El segmento cdn no colisiona con ninguna
colección: las rutas de colección tienen uno o dos segmentos y las de fichero tres o cuatro, así que una
colección llamada cdn sigue respondiendo con normalidad en /api/cms/cdn.
En /cdn/:collection/:id/:filename, :filename tiene que ser el nombre guardado del fichero: con otro
responde 404, como un id que no existe. Lo decide después del acceso. Ver
Ficheros.
Las cuatro acciones viajan como parámetro de consulta y no como rutas nuevas porque una ruta de
colección de tres segmentos es un 404. Un ?action= desconocido, o ausente donde hace falta —un
PUT sin acción, por ejemplo—, responde 400 con código INVALID_ACTION. El POST sin action es
la subida de un solo golpe de toda la vida y no cambia.
Subir es una escritura y exige sesión, las cinco formas, o lo que decida la función de create de
una colección upload tuya. Servir es una lectura y respeta el access.read de su colección. Si el
config declara alguna función de access, la subida de un anónimo se lee entera antes de contestar 401:
ver lo que el control de acceso no cubre.
Las carpetas reservadas de ssd
Sección titulada «Las carpetas reservadas de ssd»La biblioteca del CMS, ssd, guarda en carpetas que empiezan por . sus propios ficheros —.system
es donde Ajustes pone el favicon y el logo— y REST no deja tocarlas desde fuera de esa pantalla:
| Petición | Qué contesta |
|---|---|
GET /api/cms/ssd y /ssd/count sin sesión |
401, salvo que el config declare media: { access: { list: 'public' } } — ver Sesión |
GET /api/cms/ssd y /ssd/count con sesión |
Las omiten. Un ?where[folder][equals]=.system no vuelve a ensancharlo: las dos condiciones se suman |
GET /api/cms/ssd/:id de una fila reservada |
404, lo mismo que un id que no existe. También con ?select=, y también sin sesión |
PATCH y DELETE sobre una |
400 con un issue de código RESERVED_FOLDER |
POST /api/cms/ssd/upload con folder reservado |
400 RESERVED_FOLDER, y no se escribe nada, tampoco en ?action=create |
GET /api/cms/cdn/ssd/<id>/<fichero> de una |
200, sin sesión. Sus bytes sí se sirven: de eso vive el <link rel="icon"> del panel |
Lo que se cierra es el listado —por carpeta y por sesión—, no el fichero. La API local las sigue leyendo —es por donde la
pantalla de Ajustes encuentra su almacén—, pero escribir en ellas tampoco es libre ahí: ssd.update
lanza el mismo RESERVED_FOLDER sin excepción, y las únicas escrituras que pasan son las de Ajustes,
que sube y borra por la vía explícita { system: true } de upload y delete.
.system es de Ajustes: lo que tu código deje ahí con { system: true } por la API local sin que
ningún ajuste lo nombre aparece, a la hora de subirse, en la sección «Ficheros sueltos» de
Ajustes, y cualquiera con sesión en el panel lo puede reclamar. La reclamación da por hecho que D1,
R2 y KV son del mismo despliegue: compartir D1 y R2 entre dos despliegues con namespaces de KV
distintos no está soportado, porque el favicon y el logo de uno saldrían como sueltos en el otro.
Un folder que sea el slug de una colección upload tuya también se rechaza al subir, con código
FIXED_FOLDER: esa carpeta tiene su propia tabla y se sube a ella por su propia ruta.
La subida por trozos
Sección titulada «La subida por trozos»Para ficheros que no caben en una sola petición. El troceado lo hace el cliente; el servidor no
guarda nada entre una petición y la siguiente: le devuelves lo que te dio create —id,
uploadId, key y el filename— y él vuelve a deducir la clave, que es determinista. Ver
Ficheros para los límites y
Limitaciones para el techo.
-
Abrir. Aquí se valida todo lo que se puede validar sin bytes: el tamaño declarado contra
maxFileSize, y los campos de tu colección. Un campo obligatorio que falte falla ahora, no después de subir un giga.Ventana de terminal curl -X POST "https://mi-sitio.com/api/cms/ssd/upload?action=create" \-H "Cookie: <tu sesión>" \-H "Content-Type: application/json" \-d '{"filename": "video.mp4","size": 734003200,"fields": { "folder": "charlas", "alt": "La charla" }}'{"id": "0190d4c2-…","uploadId": "ABPnzm…","key": "charlas/0190d4c2-…/video.mp4","partSize": 26214400,"maxParts": 10000,"maxSize": 5368709120}La
keyes<carpeta>/<id>/<fichero>, y<id>/<fichero>cuando no hay carpeta. Enssdla carpeta sale delfolderque mandes enfields; en una colecciónuploadtuya es siempre su slug, y no se elige. -
Mandar cada trozo. El cuerpo son los bytes crudos, no
multipart/form-data. Trocea el fichero porpartSizey numera desde 1; puedes mandar varios a la vez. Guarda cadaetag. Cada petición tiene que declarar suContent-Length, o responde411: sin la cabecera no hay forma de acotar el trozo antes de leerlo.Ventana de terminal curl -X PUT "https://mi-sitio.com/api/cms/ssd/upload?action=part\&id=0190d4c2-…&uploadId=ABPnzm…&filename=video.mp4&key=charlas/0190d4c2-…/video.mp4&partNumber=1" \-H "Cookie: <tu sesión>" \-H "Content-Type: application/octet-stream" \--data-binary @trozo-1.bin{ "partNumber": 1, "etag": "5d41402a…" } -
Cerrar. Con la lista de partes; el orden da igual, se ordenan por
partNumber. Aquí es donde se olfatea el tipo, se leen las dimensiones y se inserta la fila.Ventana de terminal curl -X POST "https://mi-sitio.com/api/cms/ssd/upload?action=complete" \-H "Cookie: <tu sesión>" \-H "Content-Type: application/json" \-d '{"id": "0190d4c2-…","uploadId": "ABPnzm…","filename": "video.mp4","key": "charlas/0190d4c2-…/video.mp4","parts": [{ "partNumber": 1, "etag": "5d41402a…" }],"fields": { "alt": "La charla" }}'Responde
201con el documento creado, igual que la ruta de un solo golpe.Si repites el cierre de una subida que ya se cerró —porque perdiste la respuesta, por ejemplo— responde
409conUPLOAD_ALREADY_COMPLETED, sin datos del documento y sin tocar el almacén: la subida está hecha y no hay nada que reintentar. Para recuperar el documento, léelo por suid(el que devolviócreate) conGET /api/cms/:coleccion/:id. -
Cancelar, si algo se tuerce. Cancelar una subida que ya no existe no es un error: responde lo mismo, para que un cliente que reintenta no se quede atascado.
Ventana de terminal curl -X DELETE "https://mi-sitio.com/api/cms/ssd/upload?action=abort\&id=0190d4c2-…&uploadId=ABPnzm…&filename=video.mp4&key=charlas/0190d4c2-…/video.mp4" \-H "Cookie: <tu sesión>" \-H "Origin: https://mi-sitio.com"{ "aborted": true }
Los tamaños que devuelve create:
| Campo | Qué es |
|---|---|
partSize |
El tamaño de trozo que toca usar. 25 MiB salvo que el fichero necesite más |
maxParts |
10000, el máximo de R2 |
maxSize |
El fichero más grande que admite esta colección |
Los errores propios de estas cuatro:
| Situación | Status | code del issue |
|---|---|---|
action desconocida o ausente |
400 | INVALID_ACTION |
id que no es un UUID |
400 | INVALID_ID |
uploadId que no existe, o partes que no cuadran |
400 | INVALID_UPLOAD |
partNumber fuera de 1..10000 |
400 | OUT_OF_RANGE |
| Trozos desiguales o por debajo de 5 MiB, al cerrar | 400 | INVALID_UPLOAD |
Trozo sin Content-Length |
411 | — |
Trozo con Content-Length sobre 95 MiB |
413 | — |
size declarado sobre maxFileSize o sobre el techo |
413 | — |
Tamaño real sobre maxFileSize, al cerrar |
413 | — |
Extensión de riesgo (.exe, .html, .svg…), al abrir |
415 | — |
Tipo de riesgo o fuera de mimeTypes, al cerrar |
415 | — |
Globals
Sección titulada «Globals»Un global es un documento único sin listado, así que tiene dos rutas y no seis:
| Método | Ruta | Operación | Sesión | Éxito |
|---|---|---|---|---|
GET |
/api/cms/globals/:slug |
get |
Salvo access: { read: 'public' }, o lo que decida tu función de read |
200 |
PATCH |
/api/cms/globals/:slug |
update |
Siempre, o lo que decida tu función de update |
200 |
Un global que nadie ha guardado todavía responde 200 con sus valores por defecto, nunca 404:
no hay fila que pueda faltar. El primer guardado también es 200, no 201.
depth y select funcionan como en un documento. Los otros cuatro se descartan, pero la query entera
pasa antes por el mismo parser: un limit, un page o un depth mal formado o fuera de rango sigue
siendo 400 con QUERY_ERROR —un ?limit=abc lo es igual que en un listado—. De where y sort
solo se comprueba la forma, y su contenido no llega a mirarse: un ?sort=noexiste o un
?where[noexiste][eq]=1 responden 200, donde un listado daría 400.
| Petición | Respuesta |
|---|---|
GET /api/cms/globals a secas |
404 — Los globals no se listan: pide uno por su slug, /api/cms/globals/<slug> |
| Un slug que el config no declara | 404 — El global "<slug>" no existe, con sesión y sin ella |
Un tercer segmento (/globals/site/x) |
404, el mismo genérico de cualquier ruta que no existe |
POST, PUT, DELETE o cualquier otro verbo |
405 — "<verbo>" no se puede usar sobre un global |
PATCH sin namespace de KV declarado |
500 INTERNAL_ERROR. Es un error de despliegue, no una petición mala: el detalle (MISSING_KV) va a los logs del Worker |
El slug se resuelve antes que el método y que la sesión, así que uno que no existe es 404 para
todo el mundo; y el método antes que la sesión, así que un PUT es 405 lleve o no credenciales.
globals es, por eso, un slug reservado para colecciones: /api/cms/globals/:slug tiene la
misma forma que /api/cms/:coleccion/:id, así que una colección con ese nombre quedaría tapada sin
avisar y defineConfig la rechaza al arrancar con RESERVED_GLOBALS_SLUG. Al revés la ruta no se
tapa, pero el label derivado choca con la interfaz Globals del codegen y hace falta declarar uno:
ver Declararlo.
Ajustes
Sección titulada «Ajustes»Dos rutas más, sobre los ajustes del sitio guardados en KV:
| Método | Ruta | Qué hace | Éxito |
|---|---|---|---|
GET |
/api/cms/settings |
Los siete campos efectivos | 200 |
PATCH |
/api/cms/settings |
Fusión superficial, devuelve el resultado | 200 |
Las dos exigen sesión siempre, sin el matiz de access.read que tienen las colecciones. Un
PATCH con una clave desconocida, un valor que no es cadena o un siteUrl que no es una URL
absoluta responde 400 con su array issues.
A diferencia de cdn, este segmento sí colisionaría con una colección: /api/cms/settings tiene un
solo segmento, igual que un listado. Por eso settings es un slug reservado y defineConfig
rechaza al arrancar una colección que lo declare.
ssd es el otro slug reservado, por una razón distinta: es la biblioteca de
medios que el paquete inyecta él mismo, así que declararla sería declararla
dos veces. defineConfig también lo rechaza al arrancar, con código RESERVED_MEDIA_SLUG.
Cambiar el prefijo mueve los seis, y también las de ficheros, las de globals y la de ajustes:
export default defineConfig({ collections: [posts], api: { path: '/api/contenido' },})Parámetros de consulta
Sección titulada «Parámetros de consulta»GET /api/cms/posts ?where[status][equals]=published &where[publishedAt][less_than]=2026-01-01 &sort=-publishedAt &limit=10 &page=2 &depth=1 &select=title,slug| Parámetro | Por defecto | Rango |
|---|---|---|
limit |
10 |
entero de 1 a 1000 |
page |
1 |
entero ≥ 1 |
depth |
1 |
entero de 0 a 10 |
sort |
-createdAt |
campos separados por comas, - para descendente |
select |
todas las columnas | nombres de campo separados por comas |
where |
— | ver abajo |
Cualquiera fuera de rango responde 400 sin haber lanzado una sola consulta.
select y depth valen también al leer un documento por id. count solo mira where.
Se codifica con la sintaxis de corchetes de qs, la misma que usa Payload:
| Consulta | Query string |
|---|---|
{ status: { equals: 'published' } } |
where[status][equals]=published |
{ readingTime: { greater_than: 5 } } |
where[readingTime][greater_than]=5 |
{ slug: { in: ['a', 'b'] } } |
where[slug][in][0]=a&where[slug][in][1]=b |
{ or: [{ … }, { … }] } |
where[or][0][slug][equals]=a&where[or][1][slug][equals]=b |
{ or: [{ … }, { and: [{ … }, { … }] }] } |
where[or][0][slug][equals]=a&where[or][1][and][0][status][equals]=published&where[or][1][and][1][readingTime][greater_than]=5 |
Los once operadores y sus tipos admitidos son los de la API local, sin
recorte. Los valores viajan como cadenas y los convierte el campo, así que una fecha se escribe en ISO y un
checkbox como true:
where[publishedAt][less_than]=2026-01-01where[featured][equals]=truein y not_in aceptan como mucho 100 valores, que es el tope de parámetros que D1 liga por consulta.
and y or aceptan como mucho 100 condiciones por lista, en cualquier nivel de anidamiento. Pasarse
de cualquiera de los dos responde 400/QUERY_ERROR con el motivo; y una consulta que D1 rechace por tamaño
aunque ninguna lista supere el tope responde el mismo 400, no un 500.
Esos 100 parámetros los comparten los valores de todas las condiciones con el LIMIT del listado y, desde la
página 2, su OFFSET, y el tope de 100 de in no los descuenta. En un listado caben, pues, hasta 99 valores
con page=1 y hasta 98 desde page=2; uno más responde 400/QUERY_ERROR con
La consulta tiene demasiadas condiciones para D1: reduce el "where". /count, que no pagina, admite los 100. Más
de 100 responde el 400 que nombra el tope (admite como mucho 100 valores), y una lista de más de 101 elementos,
Ninguna lista de la consulta admite más de 100 elementos.
and y or se anidan uno dentro de otro hasta 10 niveles —where[or][0][and][0][slug][equals]=a son
dos—. Es entrada de cualquier cliente, así que tiene tope: un nivel más responde 400/QUERY_ERROR con
El "where" admite como mucho 10 niveles de "and"/"or" anidados. El tope es de la cadena de consulta;
la API local anida sin él. Y caber en el tope no obliga a D1 a aceptar el árbol:
limita la profundidad de la expresión, que se acumula con las condiciones de cada lista a lo largo de una
rama, y lo que rechaza por eso responde el mismo 400 de arriba, no un 500.
Una consulta lee como mucho 1000 parámetros (cada clave=valor separado por &, los que no son del where
incluidos). El 1001 responde 400/QUERY_ERROR con La consulta admite como mucho 1000 parámetros; no se descarta
en silencio, que dejaría sin efecto un where puesto al final.
Un operador que no existe, un campo que no existe, un operador que no aplica al tipo del campo o un valor que
el campo no sabe convertir responden 400. Ninguno se ignora en silencio: un filtro descartado devuelve filas
que no deberían estar ahí y el fallo aparece tarde.
Subcampos de un group
Sección titulada «Subcampos de un group»Se nombran por la ruta con puntos, también en sort y select:
GET /api/cms/pages?where[seo.metaTitle][equals]=A&sort=-seo.metaTitle&select=title,seo.metaTitleEl punto va dentro de los corchetes tal cual: where[seo.og.title][equals]=A. La respuesta anida el
grupo, con solo los subcampos pedidos: { "id": "…", "title": "…", "seo": { "metaTitle": "A" } }. Pedir
select=seo devuelve el grupo entero. El nombre de la columna (seo_metaTitle) responde 400/QUERY_ERROR,
como un campo que no existe. Un point solo se filtra con exists.
Respuestas
Sección titulada «Respuestas»Listado — 200:
{ "docs": [{ "id": "01J8…", "title": "Hola" }], "pagination": { "totalDocs": 42, "limit": 10, "page": 1, "totalPages": 5, "hasNextPage": true, "hasPrevPage": false }}Conteo — 200:
{ "totalDocs": 42 }Documento único — 200 con el documento. Creación — 201 con el documento. Borrado — 200 con el documento
borrado. Las tres respuestas con un documento escrito o leído por id —GET /:id, POST y PATCH— llevan
además la cabecera ETag, salvo un GET /:id con un ?select= que deje fuera
updatedAt.
En las lecturas —GET /:coleccion y GET /:coleccion/:id— y en las respuestas de POST y
PATCH lo que sale es lo que dejó el afterRead de la colección, si declara alguno: los
hooks corren dentro de la operación, así que la respuesta es la que ellos devolvieron
y no la fila cruda, y el ETag se calcula sobre ese cuerpo —del updatedAt que lleve—, de modo que un
hook que quite updatedAt deja la respuesta sin cabecera y uno que lo cambie cambia el ETag (y un
If-Match con él ya no coincidiría con el updatedAt guardado). Lo que se guarda es lo que se mandó:
un afterRead que tapa un dato lo tapa en la respuesta del POST y no en D1. Si el hook lanza, el POST o el
PATCH responde con el error del hook con la escritura ya hecha. DELETE no pasa por afterRead:
devuelve la fila borrada tal como estaba. Una subida (POST /:coleccion/upload) responde como un POST.
Errores
Sección titulada «Errores»El cuerpo lleva siempre error y message, más issues cuando es de validación:
{ "error": "VALIDATION_ERROR", "message": "El documento no es válido", "issues": [{ "path": "title", "code": "REQUIRED", "message": "title es obligatorio" }]}| Situación | Status | error |
|---|---|---|
Colección o documento inexistente, o que la condición de un access esconde a quien pregunta |
404 | NOT_FOUND |
| Cuerpo inválido | 400 | VALIDATION_ERROR |
| Consulta inválida | 400 | QUERY_ERROR |
Sin sesión donde hace falta, o donde access no deja nada a un anónimo |
401 | UNAUTHORIZED |
| Con sesión pero sin permiso | 403 | FORBIDDEN |
| Método no soportado en la ruta | 405 | METHOD_NOT_ALLOWED |
Subida sin Content-Length |
411 | LENGTH_REQUIRED |
Cerrar (?action=complete) una subida por trozos cuyo documento ya existe |
409 | UPLOAD_ALREADY_COMPLETED |
If-Match que ya no coincide con el updatedAt, o cualquier If-Match sobre un global |
412 | PRECONDITION_FAILED |
| Cuerpo mayor de 1 MB | 413 | PAYLOAD_TOO_LARGE |
Fichero de un tipo de riesgo (HTML, SVG, ejecutable) que la colección no nombra, o cuyo tipo detectado queda fuera de mimeTypes (en ssd, el de media.mimeTypes) |
415 | UNSUPPORTED_MEDIA_TYPE |
| Fallo de D1 | 500 | INTERNAL_ERROR |
Fallo del almacén de ficheros (un StorageError de R2 o de un servicio S3: credenciales rechazadas, bucket inexistente, red caída) |
500 | INTERNAL_ERROR |
Los issues de una validación son los mismos { path, code, message }
de la API local.
Quién recibe cada uno lo decide access. Sin ninguna función declarada, lo de siempre: 401 sin
sesión donde hace falta, y cualquiera con sesión pasa. Con funciones:
Qué dice access |
Sin sesión | Con sesión |
|---|---|---|
Nada para esa operación: la función da false. Sin función para esa operación, solo se niega a quien no tiene sesión (401); con sesión pasa |
401 |
403 |
| Una condición que no incluye al documento | 404, idéntico al de un id que no existe |
404, el mismo |
Una condición que sí lo incluye, o true |
La operación se hace | La operación se hace |
El 404 de una condición es a propósito el mismo cuerpo que el de un id que no existe, para que un PATCH
o un DELETE no confirme que el documento está ahí a quien no puede verlo. Por eso un PATCH anónimo
sobre un documento cuyo update devuelve una condición responde 404 y no 401: no hay forma de decir
que hace falta sesión sin decir que el documento existe. Y un campo que la persona no puede escribir
rechaza toda la petición con 400: READ_ONLY_FIELD si al menos lo puede leer, y UNKNOWN_FIELD, el
de un campo que no existe, si tampoco.
El 403 lo emite además un POST sobre la colección de sesión —la que declara auth: true—: las cuentas
se crean invitando desde el panel, no escribiendo en la colección. Sin funciones de access la respuesta
sin sesión sigue siendo 401, porque la autorización se resuelve antes. El detalle de cómo se decide
está en Control de acceso.
Una función de access que lanza, o que devuelve algo que no es un booleano ni una condición válida, no
es ninguno de los tres: es un error tuyo y sale como el 500 genérico de abajo, con el detalle
(ACCESS_ERROR) en los logs del Worker.
Un hook before* que lanza un CMSError con status menor que 500 manda
sobre la respuesta: el código y el status que le pusiste salen tal cual, así que
throw new CMSError('SIN_STOCK', 'No hay', 409) en un beforeChange contesta 409 con
"error": "SIN_STOCK". Vale para POST, PATCH y DELETE, y también para el PATCH de un
global. Un CMSError de 5xx —y cualquier otra excepción: un TypeError, un fetch que
falla— sale como el 500 genérico de arriba: un error interno nunca cuenta lo que pasó, aunque lo
haya compuesto tu hook.
Cuerpos de escritura
Sección titulada «Cuerpos de escritura»El Content-Type no se mira: lo que decide es si el cuerpo parsea como objeto JSON. Si no parsea, es 400.
Un POST con {} responde 400 con un issue por cada campo obligatorio que falta.
Un group viaja como un objeto anidado y un
point como [lng, lat]:
{ "title": "Hola", "seo": { "metaTitle": "A", "og": { "title": "B" } }, "location": [-74.07, 4.71] }En un PATCH el grupo se funde subcampo a subcampo: lo que no mandes se queda como estaba, y
"seo": null pone todos sus subcampos a null. Un subcampo required que llega en null, o que falta en
un POST, es 400 con un issue REQUIRED cuyo path es la ruta con puntos (seo.metaTitle). Un point
fuera de rango (longitud ±180, latitud ±90) o que no sea un par de números es 400.
El límite es 1 MB. Por encima es 413, y se rechaza sin llegar a parsearlo. La única excepción es
?action=complete, que admite 4 MB: su cuerpo lleva la lista de partes —10.000 caben en unos
620 KB— y ahí un 413 llegaría con el fichero ya subido, dejando una subida que no se puede cerrar.
El handler recibe una función getSession(request), que la ruta inyectada cablea a la
autenticación. Desde el navegador basta con haber iniciado sesión: la sesión
viaja en una cookie. Un cliente que no es un navegador manda una de estas credenciales:
| Cabecera | Quién actúa |
|---|---|
Cookie (la de la sesión) |
La cuenta de la sesión |
Authorization: Bearer <token> |
La cuenta de esa sesión. El token es el que devuelve el inicio de sesión en set-auth-token |
X-API-Key: <clave> |
La cuenta dueña de la clave. Solo la API REST la acepta |
Con cualquiera de las tres, la operación se evalúa igual: mismo rol, mismas funciones de access. Lo que cambia
es qué pasa cuando la credencial no vale. Un Bearer o una X-API-Key que no resuelve a una cuenta
—token caducado o de una sesión cerrada, clave revocada, regenerada, caducada, desactivada o inventada,
cuenta suspendida, cabecera mal formada— responde 401, y no cae a la cookie ni a una lectura anónima,
ni siquiera en una colección con access: { read: 'public' }. Mandar Authorization: Bearer y X-API-Key a la
vez es también un 401. Una petición sin ninguna credencial es anónima, como siempre. Los detalles y cómo
conseguir un token o una clave, en Bearer y claves de API.
| Operación | Regla |
|---|---|
GET |
Pública si la colección —o el global— declara access: { read: 'public' }; con una función de read, la decide ella; si no, requiere sesión |
GET /ssd y GET /ssd/count |
Requieren sesión, salvo que el config declare media: { access: { list: 'public' } }. Es la palanca del listado de una biblioteca que no se declara: GET /ssd/:id y las rutas de /cdn/ssd/... siguen públicas. Qué tipos admite se decide en media.mimeTypes |
POST, PATCH, DELETE |
Requieren sesión salvo que una función de create, update o delete diga otra cosa, el PATCH de un global incluido. Sin funciones, siempre. Excepción: PATCH y DELETE sobre /users sin función propia solo los puede hacer la propia cuenta o una con el rol de admin.firstUserRole (403 a cualquier otra, exista o no ese id): ver Las cuentas sin access |
GET /settings |
Requiere sesión siempre y, si el config declara access.admin, poder entrar en el panel (403 si no) |
PATCH /settings |
Lo mismo, y además access.settings de users (o, sin declararlo, el rol de admin.firstUserRole): 403 a una sesión que no puede cambiar los ajustes, también con una clave de API. Ver Quién puede cambiarlos |
defineCollection({ slug: 'posts', access: { read: 'public' }, fields: [{ name: 'title', type: 'text', required: true }],})El método se resuelve antes que la sesión, así que un PUT responde 405 lleve o no credenciales: pedir
autenticación para una ruta que no existe es confirmar que existe.
Un cliente que no es un navegador (un script, un servidor o curl) debe enviar la cabecera Origin con el
origen de tu sitio en cada POST, PUT, PATCH o DELETE que lleve un cuerpo multipart/form-data,
application/x-www-form-urlencoded o text/plain (como las subidas a /api/cms/:collection/upload) o que
no declare ningún Content-Type, como un DELETE sin cuerpo. Sin ella, Astro responde 403 antes de llegar
al handler: es su comprobación security.checkOrigin, que sigue activa. Los cuerpos JSON con
Content-Type: application/json no pasan por esa comprobación. Esto también aplica a los clientes que se
autentican con un token Bearer o con una clave de API: pasar de la cookie a una cabecera no desactiva esa
comprobación, y security.checkOrigin no cambia.
Desactivado por defecto: en el caso normal la API la consume el propio sitio, y el mismo origen no necesita CORS. Se activa listando orígenes:
cms(config, { cors: ['https://app.example.com'] })Con la lista puesta, Access-Control-Allow-Origin se emite solo para los orígenes que estén en ella, siempre
acompañado de Vary: Origin, y el preflight OPTIONS responde 204. Sin lista no se emite ninguna cabecera
de CORS y un OPTIONS responde 405, porque no hay preflight que atender.
El preflight responde Access-Control-Allow-Methods: GET, POST, PUT, PATCH, DELETE, OPTIONS —el PUT es
el de ?action=part, el único paso del troceado que mueve bytes— y
Access-Control-Allow-Headers: Content-Type, If-Match, Authorization, X-API-Key, ninguna de las cuatro
safelisted para el navegador. Las respuestas de verdad llevan Access-Control-Expose-Headers: ETag, que
tampoco lo es. Un origen de la lista puede, por tanto, trocear un fichero, hacer
escrituras condicionales y autenticarse con un token Bearer igual que uno del
mismo sitio. El valor del ETag también viaja en updatedAt dentro del cuerpo, por si prefieres no tocar
cabeceras.
Una clave de API en el código de una página la ve cualquiera que abra las herramientas del navegador: las claves son para servidores y scripts, no para un frontend público.
Access-Control-Allow-Credentials no se emite nunca, que es lo que hace inofensivo un * en la lista.
Lo que enruta la petición. La integración de Astro lo llama por ti desde la ruta que inyecta; esta firma solo importa si montas el CMS a mano.
function handle( request: Request, cms: { collections: Record<string, unknown> globals?: Record<string, unknown> bucket?: R2Bucket adapters?: Record<string, StorageAdapter> }, config: ResolvedConfig, options: { getSession(request: Request): Promise<unknown> | unknown settings: SettingsAPI cors?: string[] },): Promise<Response>globals es opcional para que un CMS montado a mano sin ellos siga arrancando; sin él, las dos rutas
de un global responden 404. bucket lo es por la misma razón y solo hace falta si alguna
colección guarda ficheros: sin él, /cdn/... responde 404. adapters es el mapa de perfiles de
almacenamiento que devolvió buildAPI: cada colección sirve, sube y borra con el de su perfil, y el que se
llama default toma el lugar de bucket. Sin ninguno de los dos, esa colección no tiene dónde guardar. settings, en cambio, es
obligatorio: los ajustes no salen de buildAPI(), así que se inyectan por la misma puerta
que getSession.
El cliente de D1 y el objeto de operaciones se le pasan: son los que devuelve
buildAPI. El handler no construye ninguno de los dos.