ArctonArcton
Routing

HTTP Methods

The seven method shorthands, registering several methods on one path, and how Arcton answers a method it has no handler for.

Each HTTP method has its own registration method:

import { Arcton } from '@arcton/core'

const app = Arcton()

app.get('/users/:id', ctx => ({ id: ctx.params.id }))
app.post('/users', () => ({ created: true }))
app.put('/users/:id', ctx => ({ replaced: ctx.params.id }))
app.patch('/users/:id', ctx => ({ updated: ctx.params.id }))
app.delete('/users/:id', ctx => ({ deleted: ctx.params.id }))
app.head('/users/:id', () => {})
app.options('/users', () => {})

app.listen()

The seven available are get, post, put, delete, patch, head and options. They behave identically apart from the method they answer, and all of them accept the same two call shapes — a handler with optional route middleware, or an options object with schemas.

Several methods on one path

Register them one at a time. Because every call returns the app, a resource reads as a block:

import { Arcton } from '@arcton/core'

const app = Arcton()

app
  .get('/users/:id', ctx => ({ id: ctx.params.id }))
  .put('/users/:id', ctx => ({ replaced: ctx.params.id }))
  .delete('/users/:id', ctx => ({ deleted: ctx.params.id }))

app.listen()

Registering the same method and path twice throws at registration — see Registration errors.

Every method on one path

app.all() registers the same handler for all seven methods above in one call. It's mainly for delegating a whole path — often a wildcard subtree — to an external Request/Response handler, e.g. mounting a library like better-auth:

import { Arcton } from '@arcton/core'

declare const auth: { handler: (request: Request) => Promise<Response> }

const app = Arcton()

app.all('/api/auth/*path', ctx => auth.handler(ctx.request))

app.listen()

all isn't a wildcard for arbitrary or non-standard HTTP verbs — it expands to exactly the same seven methods get/post/etc. answer. A request with some other verb still gets 405 (if the path matches something else) or 404.

Because it shares the same handler across all seven methods, registering all() and then a specific method on the same path — in either order — throws the same "Duplicate route" error as registering that method twice; see Registration errors. And like a wildcard segment anywhere else, /api/auth/*path needs at least one segment to match — a bare /api/auth needs its own registration too, if you need it.

Method not allowed

When a request's path matches but its method has no handler, Arcton answers 405 with an Allow header listing the methods that path does answer:

import { Arcton } from '@arcton/core'

const app = Arcton()

app.get('/users/:id', ctx => ({ id: ctx.params.id }))
app.post('/users/:id', ctx => ({ updated: ctx.params.id }))

app.listen()

DELETE /users/42 returns 405 with Allow: GET, POST and an empty body.

The path that answers is the most specific one that matched, and matching does not continue past it looking for another pattern that supports the method — Precedence works through the consequences.

HEAD and OPTIONS

Both are ordinary methods here: they answer when you register them.

import { Arcton } from '@arcton/core'

const app = Arcton()

app.get('/users/:id', ctx => ({ id: ctx.params.id }))

app.head('/users/:id', ctx => {
  ctx.response.headers.set('Content-Type', 'application/json')
})

app.options('/users/:id', ctx => {
  ctx.response.status = 204
  ctx.response.headers.set('Allow', 'GET, HEAD, OPTIONS')
})

app.listen()

For cross-origin preflight requests, @arcton/cors handles the OPTIONS exchange for you, and it only intercepts requests that carry Access-Control-Request-Method — so an app.options() route you register for your own purposes keeps working alongside it.

Choosing a status code

A handler answers 200 unless you say otherwise. Set ctx.response.status before returning:

import { Arcton } from '@arcton/core'

const app = Arcton()

app.post('/users', ctx => {
  ctx.response.status = 201
  ctx.response.headers.set('Location', '/users/42')

  return { id: '42' }
})

app.delete('/users/:id', ctx => {
  ctx.response.status = 204
})

app.listen()

204, 205 and 304 always send an empty body, whatever the handler returns. See Response.

On this page