webiny-http-route

name	webiny-http-route
context	webiny-extensions
description	Adding custom HTTP routes to the API using Api.Route and Route.Interface. Use this skill when the developer wants to expose a custom HTTP endpoint (GET, POST, PUT, etc.) on the API Gateway alongside the GraphQL handler, implement Route.Interface with full DI support, or register a custom HTTP handler in webiny.config.tsx.

Custom HTTP Routes

TL;DR

Add a custom HTTP route by implementing Route.Interface and registering it with <Api.Route> in webiny.config.tsx. The path and method props configure API Gateway and Fastify route registration. Your handler receives a framework-agnostic Route.Request and Route.Reply and supports full DI (Logger, BuildParams, UseCases, etc.).

YOU MUST include the full file path with the .ts extension in the src prop. For example, use src={"/extensions/MyRoute.ts"}, NOT src={"/extensions/MyRoute"}. Omitting the file extension will cause a build failure.

YOU MUST use export default for the createImplementation() call when the file is targeted directly by a src prop. Named exports cause build failures here.

The Route Pattern

// extensions/MyRoute.ts
import { Route } from "webiny/api/route";
import { Logger } from "webiny/api/logger";
import { BuildParams } from "webiny/api/build-params";

class MyRouteImpl implements Route.Interface {
  constructor(
    private logger: Logger.Interface,
    private buildParams: BuildParams.Interface
  ) {}

  async execute(request: Route.Request, reply: Route.Reply): Promise<void> {
    this.logger.info("Handling request", { url: request.url });

    const config = this.buildParams.get<string>("MY_CONFIG");

    reply.code(200).send({ status: "ok", config });
  }
}

export default Route.createImplementation({
  implementation: MyRouteImpl,
  dependencies: [Logger, BuildParams]
});

Register in webiny.config.tsx:

<Api.Route method={"POST"} path={"/my-route"} src={"/extensions/MyRoute.ts"} />

Props Reference

Prop	Type	Required	Description
path	string	Yes	Route path — must start with /
method	string	Yes	HTTP method (see list below)
src	string	Yes	Path to the handler file (must include .ts extension)
routeName	string	No	Pulumi resource name (kebab-case). Auto-derived from path+method if omitted

Supported HTTP Methods

DELETE, GET, HEAD, PATCH, POST, PUT, OPTIONS, ANY

Use ANY to match all HTTP methods on a given path.

Route.Request / Route.Reply Interfaces

These are framework-agnostic — no Fastify types leak into user code.

Route.Request

interface Route.Request {
    body: unknown;
    headers: Record<string, string | string[] | undefined>;
    method: string;
    url: string;
    params: unknown;   // path parameters, e.g. { id: "abc" }
    query: unknown;    // query string parameters
}

Route.Reply

interface Route.Reply {
    code(statusCode: number): this;   // set HTTP status code
    send(data?: unknown): void;       // send response body
    header(key: string, value: unknown): this;
}

Chaining example:

reply.code(201).header("X-Custom", "value").send({ created: true });

How It Works

The <Api.Route> extension does two things at build/deploy time:

1. Build time — injects two entries into apps/api/graphql/src/extensions.ts:

   • A createContextPlugin that registers your handler in the DI container
   • A createRoute that registers the Fastify route with the hardcoded path and method

2. Deploy time (Pulumi) — calls graphql.addRoute({ name, path, method }) on the ApiGraphql module to create the API Gateway route

At request time, the handler is resolved from the DI container — so all dependencies (Logger, BuildParams, UseCases, etc.) are fully injected.

Example with Path Parameters

// extensions/GetOrderRoute.ts
import { Route } from "webiny/api/route";
import { Logger } from "webiny/api/logger";

interface OrderParams {
  orderId: string;
}

class GetOrderRouteImpl implements Route.Interface {
  constructor(private logger: Logger.Interface) {}

  async execute(request: Route.Request, reply: Route.Reply): Promise<void> {
    const { orderId } = request.params as OrderParams;
    this.logger.info("Fetching order", { orderId });

    // ... fetch and return order
    reply.code(200).send({ orderId, status: "fulfilled" });
  }
}

export default Route.createImplementation({
  implementation: GetOrderRouteImpl,
  dependencies: [Logger]
});

<Api.Route method={"GET"} path={"/orders/{orderId}"} src={"/extensions/GetOrderRoute.ts"} />

Key Rules

• path and method are hardcoded at build time — the Fastify route is registered before any request arrives. Your handler does not need to specify them.
• DI is fully available in execute() — the handler instance is resolved from the container per request, so all dependencies are injected normally.
• One handler per file — each src file exports one Route.createImplementation result.
• Constructor param order must match the dependencies array exactly.
• Use .js extensions in all relative imports inside the handler file (ESM).
• Do not read process.env at runtime — use BuildParams for configuration instead.

Quick Reference

Import (handler):  import { Route } from "webiny/api/route";
Interface:         Route.Interface
Request type:      Route.Request
Reply type:        Route.Reply
Export:            Route.createImplementation({ implementation, dependencies })
Register:          <Api.Route method={"POST"} path={"/my-route"} src={"/extensions/MyRoute.ts"} />
Deploy:            yarn webiny deploy api --env=dev

Related Skills

• webiny-api-architect — DI patterns, Services, UseCases, feature organization
• webiny-custom-graphql-api — Custom GraphQL endpoints (alternative to HTTP)
• webiny-dependency-injection — Injectable services catalog (Logger, BuildParams, etc.)
• webiny-infrastructure-extensions — Pulumi-level infrastructure customization