GET, POST, PUT, PATCH, DELETE

The HTTP method handlers a route.ts exports: what they receive, what they may return, and how each method is answered.

import { notFound, type RouteHandler } from '@gio.js/core';
import { db } from '../../../../lib/db.server.ts';

export const GET: RouteHandler<'/api/items/:id'> = async (req) => {
  const item = await db.items.find(req.params.id);
  if (item === null) notFound();                  // {"error":"Not Found"}, 404
  return item;                                    // JSON, 200
};

export const DELETE: RouteHandler<'/api/items/:id'> = async (req) => {
  await db.items.delete(req.params.id);
  return null;                                    // 204
};

A route.ts (or route.js) turns its folder into an endpoint. Each named export GET, POST, PUT, PATCH or DELETE that is a function handles that method. They can be declared as functions or as constants, sync or async.

Reference

Parameters

Each handler receives one GioRequest<Route>:

Returns

Behavior

• HEAD is answered by the GET handler, without the body. HEAD and OPTIONS cannot be exported: only the five methods above are read.
• Other methods answer 405 with {"error":"Method Not Allowed"} and an Allow header listing what the file exports (plus HEAD when it exports GET). OPTIONS is answered the same way.
• A page in the same folder serves the methods the route.ts does not export: GET/HEAD render the page, and POST runs its action. A 405 from that folder lists both files' methods.
• Errors. notFound() answers 404 {"error":"Not Found"}. A body error from json() or formData() answers 415 or 400 (see request body errors) and is not logged. Any other thrown error answers 500 {"error":"Internal Server Error","digest":"..."}; the message and stack are logged under the digest, never sent.
• A route.ts that throws while it is imported answers that 500 for every method, OPTIONS included, and keeps its URL: no sibling page or 404 takes over. In development the response carries the import error.
• Never cached. Handler responses are not stored or shared between requests, and get no default Cache-Control (an event stream gets no-cache, a redirect() gets private, no-cache unless its headers set one). Set one on the Response for browsers and CDNs.
• Checks before the handler. A cross-site POST, PUT, PATCH or DELETE gets 403 from the CSRF check, and a body over [server] max_body_bytes gets 413, before your code runs.

Types

RouteHandler (RouteHandler<Route>) types a whole handler, and GioRequest (GioRequest<Route>) the request alone. Route is a pattern of your app ('/api/items/:id') or a params shape ({ id: string }).

Examples

Create from JSON

import type { GioRequest } from '@gio.js/core';
import { db } from '../../../lib/db.server.ts';

export async function POST(req: GioRequest) {
  const { text } = req.json<{ text: string }>();      // 415 unless sent as JSON
  const note = await db.notes.insert({ text });
  return Response.json(note, { status: 201, headers: { location: `/api/notes/${note.id}` } });
}

Redirect from a handler

Return (or throw) redirect(). A relative URL is sent as written:

import { redirect } from '@gio.js/core';

export function POST() {
  return redirect('/thanks');                     // 303, Location: /thanks
}

Server-Sent Events

import { GioEventStream } from '@gio.js/core';

export function GET() {
  return new GioEventStream((stream) => {
    const timer = setInterval(() => stream.send({ time: Date.now() }), 1000);
    return () => clearInterval(timer);            // runs when the client disconnects
  });
}

Set several cookies

import { serializeCookie } from '@gio.js/core';

export function POST() {
  const headers = new Headers();
  headers.append('set-cookie', serializeCookie('theme', 'dark', { httpOnly: false }));
  headers.append('set-cookie', serializeCookie('lang', 'en', { httpOnly: false }));
  return new Response(null, { status: 204, headers });
}

Good to know

• Response.redirect('/path') throws a TypeError (a 500): the web standard accepts only an absolute URL there. Use redirect(), or a Response with a location header.
• A redirect answering a <GioForm> submission (a 301/302/303 to a request with x-gio-form: 1) becomes a 204 with x-gio-redirect, as it does for page actions.
• Exporting wsHandler from the same file adds a WebSocket endpoint at the same path - see wsHandler.
• Under gio export route handlers are skipped: a static host has no server to run them.
• CORS is yours to answer: there is no OPTIONS export, so a preflight gets 405. Add the CORS headers to your responses (or a [[headers]] rule) for simple requests.

Related

• Route Handlers - the guide, with streaming responses
• route.ts
• GioEventStream, cookies, request body errors
• wsHandler
• [security.csrf]

Version history