ApiRouteDefinition

Segmentos dinámicos de la ruta, como cadenas obligatorias.

Query string; sus campos aceptan cadenas o listas de cadenas.

Cuerpo JSON (application/json, hasta 1 MiB) y, con form (desde 1.7), el de un formulario nativo.

Schema de la respuesta; obligatorio salvo con contentType: "response" o status: 204.

Estado HTTP de la respuesta correcta (desde 1.2): 200 por defecto, 201 al crear, 202 al aceptar trabajo diferido o 204 sin cuerpo. Con 200, 201 y 202 la respuesta sigue siendo JSON validado con response; con 204 el handler no devuelve nada y no se declara response. No se combina con contentType: "response". Debe ser un literal para que el generador lo lea.

"required" responde 401 UNAUTHENTICATED sin sesión.

Comprobación de Origin en las peticiones POST, PUT, PATCH y DELETE. Desde 1.8, por defecto (sin origin) responden 403 INVALID_ORIGIN si su Origin falta, es null o no es el de la aplicación ni uno de SessionManager.allowedOrigins, haya o no sesión. "required" (desde 1.2) equivale al valor por defecto y lo deja explícito.

"none" (desde 1.2, inseguro) desactiva la comprobación en las peticiones sin sesión, también en un formulario nativo (form), para webhooks (incluidos los que envían application/x-www-form-urlencoded), APIs públicas y clientes que no envían Origin, y permite que session.create() cree una sesión sin un Origin permitido. Expone la ruta al CSRF y al login CSRF: úsela sólo con otra prueba de que la petición no viene de otra web, como una firma o un token. Una petición con sesión sigue exigiendo Origin y el token CSRF.

Límite de peticiones (desde 1.2), como { limit: 5, window: "5m" }: por encima responde 429 RATE_LIMITED con Retry-After, tras Origin y CSRF y antes de auth, authorize, la entrada y el handler. Cuenta en el store de sesiones (Redis entre instancias) y, si el store falla, la petición se rechaza.

"response" deja que el handler devuelva su propio Response.

Acepta también formularios HTML nativos (desde 1.7): application/x-www-form-urlencoded y multipart/form-data, validados con el mismo schema de body. Un envío correcto responde 303 See Other a redirect, al campo return o a la página de Referer; un error vuelve a esa página con 303 y su estado, que useForm({ action }) pinta en el SSR. Exige siempre un Origin permitido. Sin form, esos tipos responden 415 UNSUPPORTED_MEDIA_TYPE.

Devolver false responde 403 FORBIDDEN.

Calcula un valor por petición que el handler recibe como locals (desde 1.2), como el usuario actual. Se ejecuta tras Origin, CSRF, auth, authorize y la validación de la entrada, y justo antes del handler; un ApiError que lance (por ejemplo 401 o 403) es la respuesta. Declárelo antes de handler para que TypeScript infiera su tipo.

Recibe la entrada validada, el contexto y locals; su resultado se valida con response. Con status: 204 no devuelve nada.