routes

Details #

A route lets other programs talk to your extension over HTTP: a webhook sender, a script, curl. The engine serves it on its local API at /ext/<extension id>/<path> and hands the request to your handler.

Declare it in switchboard.json under adds.routes. Every entry has an id (lowercase, digits and . _ -, up to 64 characters, starting with a letter), a title (1 to 80 characters), a path and an optional description and method. Ids must be unique within the list.

{
  "adds": {
    "routes": [
      { "id": "status", "title": "Status", "path": "/status", "method": "GET" }
    ]
  }
}

route('status', async (req, ctx) => ({ status: 200, body: { ok: true, seen: req.query } }))

With the extension id com.example.hooks, that route answers GET /ext/com.example.hooks/status. It uses the engine's normal API address and the same API token as other API calls.

Gotchas #

• The handler has 15 seconds.

• A request that matches no route answers 404. A handler that throws answers 502 with its message.

• The manifest checks the entry's shape; the handler does the work. Without a matching handler the extension doesn't load.

• Unknown keys in an entry are refused.

Handler #

The handler gets { method, path, query, body }. path is the part after the extension id, without the leading slash. query is an object of strings. body is the request body parsed as JSON, or the raw text (up to 1 MB) when it isn't JSON.

It returns { status, body }. Both are optional: the status defaults to 200. Returning any other JSON answers 200 with that JSON as the body.

Full example #

The Full example above is a working extension, a small inbox with a POST /inbox route and a GET /inbox route. You can download it from the Full example section and edit it into your own.

See also #

• actions