Skip to main content

Class: HttpRouter

server.HttpRouter

HTTP router for specifying the paths and methods of httpActionGenerics

An example convex/http.js file might look like this.

import { httpRouter } from "convex/server";
import { getMessagesByAuthor } from "./getMessagesByAuthor";
import { httpAction } from "./_generated/server";

const http = httpRouter();

// HTTP actions can be defined inline...
http.route({
path: "/message",
method: "POST",
handler: httpAction(async ({ runMutation }, request) => {
const { author, body } = await request.json();

await runMutation(api.sendMessage.default, { body, author });
return new Response(null, {
status: 200,
});
})
});

// ...or they can be imported from other files.
http.route({
path: "/getMessagesByAuthor",
method: "GET",
handler: getMessagesByAuthor,
});

// Convex expects the router to be the default export of `convex/http.js`.
export default http;

Constructors

constructor

new HttpRouter()

Properties

exactRoutes

exactRoutes: Map<string, Map<"GET" | "POST" | "PUT" | "DELETE" | "OPTIONS" | "PATCH", PublicHttpAction>>

Defined in

server/router.ts:143


prefixRoutes

prefixRoutes: Map<"GET" | "POST" | "PUT" | "DELETE" | "OPTIONS" | "PATCH", Map<string, PublicHttpAction>>

Defined in

server/router.ts:144


isRouter

isRouter: boolean = true

Defined in

server/router.ts:145

Methods

route

route(spec): void

Specify an HttpAction to be used to respond to requests for an HTTP method (e.g. "GET") and a path or pathPrefix.

Paths must begin with a slash. Path prefixes must also end in a slash.

// matches `/profile` (but not `/profile/`)
http.route({ path: "/profile", method: "GET", handler: getProfile})

// matches `/profiles/`, `/profiles/abc`, and `/profiles/a/c/b` (but not `/profile`)
http.route({ pathPrefix: "/profile/", method: "GET", handler: getProfile})

Parameters

NameType
specRouteSpec

Returns

void

Defined in

server/router.ts:161


getRoutes

getRoutes(): readonly [string, "GET" | "POST" | "PUT" | "DELETE" | "OPTIONS" | "PATCH", (...args: any[]) => any][]

Returns a list of routed HTTP actions.

These are used to populate the list of routes shown in the Functions page of the Convex dashboard.

Returns

readonly [string, "GET" | "POST" | "PUT" | "DELETE" | "OPTIONS" | "PATCH", (...args: any[]) => any][]

  • an array of [path, method, endpoint] tuples.

Defined in

server/router.ts:229


lookup

lookup(path, method): null | readonly [PublicHttpAction, "GET" | "POST" | "PUT" | "DELETE" | "OPTIONS" | "PATCH", string]

Returns the appropriate HTTP action and its routed request path and method.

The path and method returned are used for logging and metrics, and should match up with one of the routes returned by getRoutes.

For example,

http.route({ pathPrefix: "/profile/", method: "GET", handler: getProfile});

http.lookup("/profile/abc", "GET") // returns [getProfile, "GET", "/profile/*"]

Parameters

NameType
pathstring
method"GET" | "POST" | "PUT" | "DELETE" | "OPTIONS" | "PATCH" | "HEAD"

Returns

null | readonly [PublicHttpAction, "GET" | "POST" | "PUT" | "DELETE" | "OPTIONS" | "PATCH", string]

Defined in

server/router.ts:275


runRequest

runRequest(argsStr): Promise<string>

Given a JSON string representation of a Request object, return a Response by routing the request and running the appropriate endpoint or returning a 404 Response.

Parameters

NameTypeDescription
argsStrstringa JSON string representing a Request object.

Returns

Promise<string>

  • a Response object.

Defined in

server/router.ts:301