# Overview The `HttpApi` modules let you describe your HTTP API once and use that description to run a server, generate documentation, and create a type-safe client. An API is built from three building blocks: - **HttpEndpoint** — a single route (path + HTTP method) with schemas for its request and response. - **HttpApiGroup** — a collection of related endpoints (e.g., all user-related routes). - **HttpApi** — the top-level object that combines groups into a complete API. ``` HttpApi ├── HttpGroup │ ├── HttpEndpoint │ └── HttpEndpoint └── HttpGroup ├── HttpEndpoint ├── HttpEndpoint └── HttpEndpoint ``` From one API definition you can: - **Start a server** that implements and serves every endpoint. - **Generate documentation** (Scalar or Swagger) automatically. - **Derive a client** with a typed method for each endpoint. One definition powers the server, docs, and client — change it once and everything stays in sync. # Getting Started ## Defining and Implementing an API Let's build a minimal API with one endpoint that returns `"Hello, World!"`. You'll define what the endpoint looks like, implement it, and start a server. ``` HttpApi ("MyApi") └── HttpGroup ("Greetings") └── HttpEndpoint ("hello-world") ``` **Example** (Hello World) ```ts import { NodeHttpServer, NodeRuntime } from "@effect/platform-node" import { Effect, Layer, Schema } from "effect" import { HttpRouter } from "effect/http" import { HttpApi, HttpApiBuilder, HttpApiEndpoint, HttpApiGroup } from "effect/http-api" import { createServer } from "node:http" // Definition const Api = HttpApi.make("MyApi").add( // Define the API group HttpApiGroup.make("Greetings").add( // Define the endpoint HttpApiEndpoint.get("hello", "/", { // Define the success schema success: Schema.String }) ) ) // Implementation const GroupLayer = HttpApiBuilder.group( Api, "Greetings", // The name of the group to handle (handlers) => handlers.handle( "hello", // The name of the endpoint to handle () => Effect.succeed("Hello, World!") // The handler function ) ) // Server const ApiLayer = HttpApiBuilder.layer(Api).pipe( Layer.provide(GroupLayer), HttpRouter.serve, Layer.provide(NodeHttpServer.layer(createServer, { port: 3000 })) ) // Launch Layer.launch(ApiLayer).pipe(NodeRuntime.runMain) ``` After running the code, open a browser and navigate to http://localhost:3000. The server will respond with: ``` Hello, World! ``` ## Serving The Auto Generated OpenAPI Documentation Adding a documentation layer gives you an interactive page where you (and your API consumers) can explore endpoints, try requests, and see response shapes — all generated automatically from your API definition. You can choose between the `HttpApiScalar` module (Scalar UI) or the `HttpApiSwagger` module (Swagger UI); both do the same job. **Example** (Serving Scalar Documentation) To include Scalar in your server setup, provide the `HttpApiScalar.layer` when configuring the server. ```ts const ApiLayer = HttpApiBuilder.layer(Api).pipe( // Provide the Scalar layer so clients can access auto-generated docs Layer.provide(GroupLayer), Layer.provide(HttpApiScalar.layer(Api)), HttpRouter.serve, Layer.provide(NodeHttpServer.layer(createServer, { port: 3000 })) ) ``` After running the server, open your browser and navigate to http://localhost:3000/docs. This URL will display the Scalar documentation, allowing you to explore the API's endpoints, request parameters, and response structures interactively. **Example** (Serving Swagger Documentation) To include Swagger in your server setup, provide the `HttpApiSwagger.layer` when configuring the server. ```ts const ApiLayer = HttpApiBuilder.layer(Api).pipe( Layer.provide(GroupLayer), // Provide the Swagger layer so clients can access auto-generated docs Layer.provide(HttpApiSwagger.layer(Api)), // "/docs" is the default path. // or Layer.provide(HttpApiScalar.layer(Api)), HttpRouter.serve, Layer.provide(NodeHttpServer.layer(createServer, { port: 3000 })) ) ``` After running the server, open your browser and navigate to http://localhost:3000/docs. This URL will display the Swagger documentation, allowing you to explore the API's endpoints, request parameters, and response structures interactively. ## Adding Annotations to Schemas Annotations attach extra information to your schemas — like a human-readable description or an identifier shown in the docs UI. They don't change runtime behavior; they enrich the generated documentation. ```ts const User = Schema.Struct({ id: Schema.Int, name: Schema.String }).annotate({ description: "A user", // The description of the user identifier: "User" // Used in the Scalar UI under the Model section }) ``` ## Deriving a Client Once you've defined an API, you can generate a fully typed client from it using the `HttpApiClient` module. The client gives you a method for every endpoint, so calling your API feels like calling a local function — with full type safety and no manual HTTP handling. **Example** (Deriving and Using a Client) ```ts import { NodeHttpServer, NodeRuntime } from "@effect/platform-node" import { Effect, Layer, Schema } from "effect" import { HttpRouter } from "effect/http" import { FetchHttpClient } from "effect/http" import { HttpApi, HttpApiBuilder, HttpApiClient, HttpApiEndpoint, HttpApiGroup } from "effect/http-api" import { createServer } from "node:http" const Api = HttpApi.make("MyApi") .add( HttpApiGroup.make("Greetings") .add( HttpApiEndpoint.get("hello", "/", { success: Schema.String }) ) ) const GroupLayer = HttpApiBuilder.group( Api, "Greetings", (handlers) => handlers.handle("hello", () => Effect.succeed("Hello, World!")) ) const ApiLayer = HttpApiBuilder.layer(Api).pipe( Layer.provide(GroupLayer), HttpRouter.serve, Layer.provide(NodeHttpServer.layer(createServer, { port: 3000 })) ) Layer.launch(ApiLayer).pipe(NodeRuntime.runMain) // Create a program that derives and uses the client const program = Effect.gen(function*() { // Derive the client const client = yield* HttpApiClient.make(Api, { baseUrl: "http://localhost:3000" }) // Call the "hello-world" endpoint const hello = yield* client.Greetings.hello() console.log(hello) }) // Provide a Fetch-based HTTP client and run the program Effect.runFork(program.pipe(Effect.provide(FetchHttpClient.layer))) /* Output: [18:55:26.051] INFO (#2): Listening on http://0.0.0.0:3000 [18:55:26.057] INFO (#12) http.span=2ms: Sent HTTP response { 'http.method': 'GET', 'http.url': '/', 'http.status': 200 } Hello, World! */ ``` # Design Principles - **Schemas first**: Every piece of data flowing in or out of an endpoint — path params, query strings, headers, payloads, responses, and errors — is described by a schema. The framework uses these schemas to validate requests, serialize responses, generate docs, and type the client. - **Metadata lives on schemas**: Configuration like HTTP status codes and content types is attached directly to the schema via annotations, not to the endpoint. This keeps all the information about a data shape in one place. In particular: - **Request** - **Payload encoding / content type** is controlled with `HttpApiSchema.as*` helpers: - `asJson` — parse the body as JSON (default) - `asFormUrlEncoded` — parse the body as URL-encoded form data - `asText` — parse the body as plain text - `asUint8Array` — parse the body as raw binary data - `asMultipart` — parse the body as a multipart form (for file uploads) - `asMultipartStream` — parse the body as a streaming multipart form - **Response** - **Status code** is set via the `HttpApiSchema.status` API (or `httpApiStatus` annotation) - **Encoding / content type** is controlled with `HttpApiSchema.as*` helpers: - `asJson` — send the body as JSON (default) - `asFormUrlEncoded` — send the body as URL-encoded form data - `asText` — send the body as plain text - `asUint8Array` — send the body as raw binary data ## Anatomy of an Endpoint An endpoint definition describes everything the framework needs to know about a single HTTP route: which URL parameters it expects, what query strings and headers it reads, what the request body looks like, and what it can respond with (both successes and errors). All of these are optional. `HttpApiEndpoint` automatically coerces request and response schemas by default. Path / query / header schemas use `Schema.toCodecStringTree`, while JSON payload / success / error schemas use `Schema.toCodecJson`. This means you can define schemas in their natural domain types (for example `Schema.Int`), without manually adding string / JSON transformations. ```ts const User = Schema.Struct({ id: Schema.String, name: Schema.String }) // ┌─── Endpoint name (used in the client as the method name) // │ ┌─── Endpoint path // ▼ ▼ HttpApiEndpoint.patch("updateUser", "/user/:id", { // Parameters from the route pattern (e.g. /user/:id). // Can be a record of fields or a full schema. params: { // ┌─── Schema for the "id" parameter. // ▼ id: Schema.String }, // (optional) Query string parameters (e.g. ?mode=merge). // Can be a record of fields or a full schema. query: { // ┌─── Schema for the "mode" query parameter // ▼ mode: Schema.Literals(["merge", "replace"]) }, // (optional) Request headers. // Can be a record of fields or a full schema. headers: { "x-api-key": Schema.String, "x-request-id": Schema.String }, // The request payload can be a single schema or an array of schemas. // - Default encoding is JSON. // - Default status for success is 200. // For GET requests, the payload must be a record of schemas. payload: [ // JSON payload (default encoding). Schema.Struct({ name: Schema.String }), // text/plain payload. Schema.String.pipe(HttpApiSchema.asText()) ], // Possible success responses. // Default is 200 OK with no content if omitted. success: [ // JSON response (default encoding). User, // text/plain response with a custom status code. Schema.String .pipe( HttpApiSchema.status(206), HttpApiSchema.asText() ) ], // Possible error responses. error: [ // Default is 500 Internal Server Error with JSON encoding. Schema.Finite, // text/plain error with a custom status code. Schema.String .pipe( HttpApiSchema.status(404), HttpApiSchema.asText() ), // Any schema that encodes to `Schema.Void` is treated as "no content". // Here it uses a custom status code. Schema.Void .pipe(HttpApiSchema.status(401)) ] }) ``` # Routing This section walks through defining endpoints for common HTTP methods — GET, POST, DELETE, and PATCH — using a user-management API as a running example: - `GET /users` — retrieve all users. - `GET /users/:userId` — retrieve a specific user by ID. - `POST /users` — create a new user. - `DELETE /users/:userId` — delete a user by ID. - `PATCH /users/:userId` — update a user by ID. ## GET Use `HttpApiEndpoint.get` to create a GET endpoint. Provide a name (used as the method name in generated clients), a path, and optionally a `success` schema describing what the endpoint returns. Without a success schema the default response is `204 No Content`. **Example** (Defining a GET Endpoint to Retrieve All Users) ```ts import { NodeHttpServer, NodeRuntime } from "@effect/platform-node" import { Effect, Layer, Schema } from "effect" import { HttpRouter } from "effect/http" import { HttpApi, HttpApiBuilder, HttpApiEndpoint, HttpApiGroup, HttpApiScalar } from "effect/http-api" import { createServer } from "node:http" // Define a schema representing a User entity const User = Schema.Struct({ id: Schema.Int, name: Schema.String }) const Api = HttpApi.make("MyApi") .add( HttpApiGroup.make("Users") .add( // Define the "getUsers" endpoint, returning a list of users // ┌─── Endpoint name (used in the client as the method name) // │ ┌─── Endpoint path // ▼ ▼ HttpApiEndpoint.get("getUsers", "/users", { // ┌─── success schema // │ // ▼ success: Schema.Array(User) }) ) ) const GroupLayer = HttpApiBuilder.group( Api, "Users", (handlers) => handlers.handle("getUsers", () => Effect.succeed( [{ id: 1, name: "User 1" }, { id: 2, name: "User 2" }] )) ) const ApiLayer = HttpApiBuilder.layer(Api).pipe( Layer.provide(GroupLayer), Layer.provide(HttpApiScalar.layer(Api)), HttpRouter.serve, Layer.provide(NodeHttpServer.layer(createServer, { port: 3000 })) ) Layer.launch(ApiLayer).pipe(NodeRuntime.runMain) ``` ## POST Use `HttpApiEndpoint.post` to create an endpoint that accepts data. The `payload` option describes the shape of the request body, and `success` describes what the endpoint returns. When a group has more than one endpoint, use `.handleAll` to register all the handlers in a single call, keyed by endpoint name. Single endpoints can still be registered one at a time with `.handle`. **Example** (Defining a POST Endpoint with Payload and Success Schemas) ```ts import { NodeHttpServer, NodeRuntime } from "@effect/platform-node" import { Effect, Layer, Schema } from "effect" import { HttpRouter } from "effect/http" import { HttpApi, HttpApiBuilder, HttpApiEndpoint, HttpApiGroup, HttpApiScalar } from "effect/http-api" import { createServer } from "node:http" const User = Schema.Struct({ id: Schema.Int, name: Schema.String }) const Api = HttpApi.make("MyApi") .add( HttpApiGroup.make("Users") .add( HttpApiEndpoint.get("getUsers", "/users", { success: Schema.Array(User) }), HttpApiEndpoint.get("getUser", "/user/:id", { params: { id: Schema.Int }, success: User }), // Define a POST endpoint for creating a new user HttpApiEndpoint.post("createUser", "/user", { // Define the request body schema (payload) payload: User, // Define the schema for a successful response success: User }) ) ) const GroupLayer = HttpApiBuilder.group( Api, "Users", (handlers) => handlers.handleAll({ getUsers: () => Effect.succeed( [{ id: 1, name: "User 1" }, { id: 2, name: "User 2" }] ), getUser: (ctx) => { const id = ctx.params.id return Effect.succeed({ id, name: `User ${id}` }) }, createUser: (ctx) => { // ┌─── User // ▼ const user = ctx.payload return Effect.succeed(user) } }) ) const ApiLayer = HttpApiBuilder.layer(Api).pipe( Layer.provide(GroupLayer), Layer.provide(HttpApiScalar.layer(Api)), HttpRouter.serve, Layer.provide(NodeHttpServer.layer(createServer, { port: 3000 })) ) Layer.launch(ApiLayer).pipe(NodeRuntime.runMain) ``` ## DELETE Use `HttpApiEndpoint.delete` to create an endpoint that removes a resource. **Example** (Defining a DELETE Endpoint with Parameters) ```ts import { NodeHttpServer, NodeRuntime } from "@effect/platform-node" import { Effect, Layer, Schema } from "effect" import { HttpRouter } from "effect/http" import { HttpApi, HttpApiBuilder, HttpApiEndpoint, HttpApiGroup, HttpApiScalar } from "effect/http-api" import { createServer } from "node:http" const User = Schema.Struct({ id: Schema.Int, name: Schema.String }) const IdParam = Schema.Int const Api = HttpApi.make("MyApi") .add( HttpApiGroup.make("Users") .add( HttpApiEndpoint.get("getUsers", "/users", { success: Schema.Array(User) }), HttpApiEndpoint.get("getUser", "/user/:id", { params: { id: IdParam }, success: User }), HttpApiEndpoint.post("createUser", "/user", { payload: User, success: User }), HttpApiEndpoint.delete("deleteUser", "/user/:id", { params: { id: IdParam } }) ) ) const GroupLayer = HttpApiBuilder.group( Api, "Users", (handlers) => handlers.handleAll({ getUsers: () => Effect.succeed( [{ id: 1, name: "User 1" }, { id: 2, name: "User 2" }] ), getUser: (ctx) => { const id = ctx.params.id return Effect.succeed({ id, name: `User ${id}` }) }, createUser: (ctx) => { const user = ctx.payload return Effect.succeed(user) }, deleteUser: (ctx) => { const id = ctx.params.id return Effect.log(`Deleting user ${id}`) } }) ) const ApiLayer = HttpApiBuilder.layer(Api).pipe( Layer.provide(GroupLayer), Layer.provide(HttpApiScalar.layer(Api)), HttpRouter.serve, Layer.provide(NodeHttpServer.layer(createServer, { port: 3000 })) ) Layer.launch(ApiLayer).pipe(NodeRuntime.runMain) ``` ## PATCH Use `HttpApiEndpoint.patch` to create an endpoint that partially updates a resource. Like POST, you can define `payload` (the fields to update) and `success` (the response after the update). **Example** (Defining a PATCH Endpoint for Updating a User) ```ts import { NodeHttpServer, NodeRuntime } from "@effect/platform-node" import { Effect, Layer, Schema } from "effect" import { HttpRouter } from "effect/http" import { HttpApi, HttpApiBuilder, HttpApiEndpoint, HttpApiGroup, HttpApiScalar } from "effect/http-api" import { createServer } from "node:http" const User = Schema.Struct({ id: Schema.Int, name: Schema.String }) const IdParam = Schema.Int const Api = HttpApi.make("MyApi") .add( HttpApiGroup.make("Users") .add( HttpApiEndpoint.get("getUsers", "/users", { success: Schema.Array(User) }), HttpApiEndpoint.get("getUser", "/user/:id", { params: { id: IdParam }, success: User }), HttpApiEndpoint.post("createUser", "/user", { payload: User, success: User }), HttpApiEndpoint.delete("deleteUser", "/user/:id", { params: { id: IdParam } }), HttpApiEndpoint.patch("updateUser", "/user/:id", { params: { id: IdParam }, // Specify the schema for the request payload payload: Schema.Struct({ name: Schema.String // Only the name can be updated }), // Specify the schema for a successful response success: User }) ) ) const GroupLayer = HttpApiBuilder.group( Api, "Users", (handlers) => handlers.handleAll({ getUsers: () => Effect.succeed( [{ id: 1, name: "User 1" }, { id: 2, name: "User 2" }] ), getUser: (ctx) => { const id = ctx.params.id return Effect.succeed({ id, name: `User ${id}` }) }, createUser: (ctx) => { const user = ctx.payload return Effect.succeed(user) }, deleteUser: (ctx) => { const id = ctx.params.id return Effect.log(`Deleting user ${id}`) }, updateUser: (ctx) => { const id = ctx.params.id return Effect.succeed({ id, name: `User ${id}` }) } }) ) const ApiLayer = HttpApiBuilder.layer(Api).pipe( Layer.provide(GroupLayer), Layer.provide(HttpApiScalar.layer(Api)), HttpRouter.serve, Layer.provide(NodeHttpServer.layer(createServer, { port: 3000 })) ) Layer.launch(ApiLayer).pipe(NodeRuntime.runMain) ``` ## Parameters Path parameters let you capture dynamic values from the URL. For example, `/user/:id` extracts the `id` segment. Use the `params` option to declare a record of fields or a full schema — the framework will parse and validate the value before your handler runs. **Example** (Defining a GET Endpoint to Retrieve a User by ID) ```ts import { NodeHttpServer, NodeRuntime } from "@effect/platform-node" import { Effect, Layer, Schema } from "effect" import { HttpRouter } from "effect/http" import { HttpApi, HttpApiBuilder, HttpApiEndpoint, HttpApiGroup, HttpApiScalar } from "effect/http-api" import { createServer } from "node:http" const User = Schema.Struct({ id: Schema.Int, name: Schema.String }) const Api = HttpApi.make("MyApi") .add( HttpApiGroup.make("Users") .add( HttpApiEndpoint.get("getUsers", "/users", { success: Schema.Array(User) }), // a GET endpoint with a parameter ":id" HttpApiEndpoint.get("getUser", "/user/:id", { params: { // ┌─── schema for the "id" parameter // ▼ id: Schema.Int }, success: User }) ) ) const GroupLayer = HttpApiBuilder.group( Api, "Users", (handlers) => handlers.handleAll({ getUsers: () => Effect.succeed( [{ id: 1, name: "User 1" }, { id: 2, name: "User 2" }] ), getUser: (ctx) => { // ┌─── number // ▼ const id = ctx.params.id return Effect.succeed({ id, name: `User ${id}` }) } }) ) const ApiLayer = HttpApiBuilder.layer(Api).pipe( Layer.provide(GroupLayer), Layer.provide(HttpApiScalar.layer(Api)), HttpRouter.serve, Layer.provide(NodeHttpServer.layer(createServer, { port: 3000 })) ) Layer.launch(ApiLayer).pipe(NodeRuntime.runMain) ``` ## Catch-All Endpoints Set the path to `"*"` to match any URL that no other endpoint handles. This is useful for custom "not found" pages or fallback responses. **Example** (Defining a Catch-All Endpoint) ```ts import { NodeHttpServer, NodeRuntime } from "@effect/platform-node" import { Effect, Layer, Schema } from "effect" import { HttpRouter } from "effect/http" import { HttpApi, HttpApiBuilder, HttpApiEndpoint, HttpApiGroup, HttpApiScalar } from "effect/http-api" import { createServer } from "node:http" const User = Schema.Struct({ id: Schema.Int, name: Schema.String }) const IdParam = Schema.Int const Api = HttpApi.make("MyApi") .add( HttpApiGroup.make("Users") .add( HttpApiEndpoint.get("getUsers", "/users", { success: Schema.Array(User) }), HttpApiEndpoint.get("getUser", "/user/:id", { params: { id: IdParam }, success: User }), HttpApiEndpoint.post("createUser", "/user", { payload: User, success: User }), HttpApiEndpoint.delete("deleteUser", "/user/:id", { params: { id: IdParam } }), HttpApiEndpoint.patch("updateUser", "/user/:id", { params: { id: IdParam }, payload: Schema.Struct({ name: Schema.String }), success: User }), // catch-all endpoint HttpApiEndpoint.get("catchAll", "*", { success: Schema.String }) ) ) const GroupLayer = HttpApiBuilder.group( Api, "Users", (handlers) => handlers.handleAll({ getUsers: () => Effect.succeed( [{ id: 1, name: "User 1" }, { id: 2, name: "User 2" }] ), getUser: (ctx) => { const id = ctx.params.id return Effect.succeed({ id, name: `User ${id}` }) }, createUser: (ctx) => { const user = ctx.payload return Effect.succeed(user) }, deleteUser: (ctx) => { const id = ctx.params.id return Effect.log(`Deleting user ${id}`) }, updateUser: (ctx) => { const id = ctx.params.id return Effect.succeed({ id, name: `User ${id}` }) }, catchAll: () => { return Effect.succeed("Not found") } }) ) const ApiLayer = HttpApiBuilder.layer(Api).pipe( Layer.provide(GroupLayer), Layer.provide(HttpApiScalar.layer(Api)), HttpRouter.serve, Layer.provide(NodeHttpServer.layer(createServer, { port: 3000 })) ) Layer.launch(ApiLayer).pipe(NodeRuntime.runMain) ``` > [!IMPORTANT] > The catch-all endpoint must be the last endpoint in the group. > [!IMPORTANT] > (OpenAPI). A catch-all endpoint is not included in the OpenAPI specification because can't be represented as a path. ## Prefixing Prefixes let you prepend a common path segment to endpoints, groups, or an entire API. This avoids repeating the same base path on every endpoint. **Example** (Using Prefixes for Common Path Management) ```ts import { NodeHttpServer, NodeRuntime } from "@effect/platform-node" import { Effect, Layer, Schema } from "effect" import { HttpRouter } from "effect/http" import { HttpApi, HttpApiBuilder, HttpApiEndpoint, HttpApiGroup, HttpApiScalar } from "effect/http-api" import { createServer } from "node:http" const Api = HttpApi.make("MyApi") .add( HttpApiGroup.make("group") .add( HttpApiEndpoint.get("endpointA", "/a", { success: Schema.String }) // Prefix for this endpoint .prefix("/endpointPrefix"), HttpApiEndpoint.get("endpointB", "/b", { success: Schema.String }) ) // Prefix for all endpoints in the group .prefix("/groupPrefix") ) // Prefix for the entire API .prefix("/apiPrefix") const GroupLayer = HttpApiBuilder.group( Api, "group", (handlers) => handlers.handleAll({ endpointA: () => Effect.succeed("Endpoint A"), endpointB: () => Effect.succeed("Endpoint B") }) ) const ApiLayer = HttpApiBuilder.layer(Api).pipe( Layer.provide(GroupLayer), Layer.provide(HttpApiScalar.layer(Api)), HttpRouter.serve, Layer.provide(NodeHttpServer.layer(createServer, { port: 3000 })) ) Layer.launch(ApiLayer).pipe(NodeRuntime.runMain) ``` You can test this endpoint using a GET request. For example: ```sh curl http://localhost:3000/apiPrefix/groupPrefix/endpointPrefix/a # Returns 200 OK curl http://localhost:3000/apiPrefix/groupPrefix/b # Returns 200 OK ``` # Request ## Query Parameters Query parameters are the `?key=value` pairs appended to a URL. Use the `query` option to declare a record of fields or a full schema — the framework will parse, validate, and type them for you. **Example** (Defining Query Parameters with Metadata) ```ts import { NodeHttpServer, NodeRuntime } from "@effect/platform-node" import { Effect, Layer, Schema } from "effect" import { HttpRouter } from "effect/http" import { HttpApi, HttpApiBuilder, HttpApiEndpoint, HttpApiGroup, HttpApiScalar } from "effect/http-api" import { createServer } from "node:http" const User = Schema.Struct({ id: Schema.Int, name: Schema.String }) const Page = Schema.Int.check(Schema.isGreaterThan(0)) const Api = HttpApi.make("MyApi") .add( HttpApiGroup.make("Users") .add( HttpApiEndpoint.get("getUsers", "/users", { success: Schema.Array(User), // Specify a schema for each query parameter query: { // Parameter "page" for pagination page: Schema.optionalKey(Page), // Parameter "sort" for sorting options sort: Schema.optionalKey(Schema.Literals(["id", "name"])) } }) ) ) const GroupLayer = HttpApiBuilder.group( Api, "Users", (handlers) => handlers .handle("getUsers", (ctx) => { const { page, sort } = ctx.query console.log(`Getting users with page ${page} and sort ${sort}`) return Effect.succeed( [{ id: 1, name: "User 1" }, { id: 2, name: "User 2" }] ) }) ) const ApiLayer = HttpApiBuilder.layer(Api).pipe( Layer.provide(GroupLayer), Layer.provide(HttpApiScalar.layer(Api)), HttpRouter.serve, Layer.provide(NodeHttpServer.layer(createServer, { port: 3000 })) ) Layer.launch(ApiLayer).pipe(NodeRuntime.runMain) ``` #### Defining an Array of Values for a Query Parameter A single query parameter can carry multiple values (e.g., `?a=1&a=2`). Wrap the parameter's schema in `Schema.Array` to accept an array of values. **Example** (Defining an Array of String Values for a Query Parameter) ```ts import { NodeHttpServer, NodeRuntime } from "@effect/platform-node" import { Effect, Layer, Schema } from "effect" import { HttpRouter } from "effect/http" import { HttpApi, HttpApiBuilder, HttpApiEndpoint, HttpApiGroup, HttpApiScalar } from "effect/http-api" import { createServer } from "node:http" const User = Schema.Struct({ id: Schema.Int, name: Schema.String }) const Api = HttpApi.make("MyApi") .add( HttpApiGroup.make("Users") .add( HttpApiEndpoint.get("getUsers", "/users", { success: Schema.Array(User), query: { a: Schema.optionalKey(Schema.Array(Schema.String)) } }) ) ) const GroupLayer = HttpApiBuilder.group( Api, "Users", (handlers) => handlers .handle("getUsers", (ctx) => { console.log(ctx.query) return Effect.succeed( [{ id: 1, name: "User 1" }, { id: 2, name: "User 2" }] ) }) ) const ApiLayer = HttpApiBuilder.layer(Api).pipe( Layer.provide(GroupLayer), Layer.provide(HttpApiScalar.layer(Api)), HttpRouter.serve, Layer.provide(NodeHttpServer.layer(createServer, { port: 3000 })) ) Layer.launch(ApiLayer).pipe(NodeRuntime.runMain) ``` You can test this endpoint by passing an array of values in the query string. For example: ```sh curl "http://localhost:3000/users?a=1&a=2" # Two values for the `a` parameter ``` The query string sends two values (`1` and `2`) for the `a` parameter. The server will process and validate these values according to the schema. Both the following requests will be valid: ```sh curl "http://localhost:3000/users" # No values for the `a` parameter curl "http://localhost:3000/users?a=1" # One value for the `a` parameter ``` ## Request Headers Use the `headers` option to declare a record of fields or a full schema for the request headers the endpoint expects. > [!IMPORTANT] > All headers are normalized to lowercase. Always use lowercase keys for the headers. **Example** (Describe and validate custom headers) ```ts import { NodeHttpServer, NodeRuntime } from "@effect/platform-node" import { Effect, Layer, Schema } from "effect" import { HttpRouter } from "effect/http" import { HttpApi, HttpApiBuilder, HttpApiEndpoint, HttpApiGroup, HttpApiScalar } from "effect/http-api" import { createServer } from "node:http" const User = Schema.Struct({ id: Schema.Int, name: Schema.String }) const Api = HttpApi.make("MyApi") .add( HttpApiGroup.make("Users") .add( HttpApiEndpoint.get("getUsers", "/users", { // Always use lowercase keys for the headers headers: { "x-api-key": Schema.String, "x-request-id": Schema.String }, success: Schema.Array(User) }) ) ) const GroupLayer = HttpApiBuilder.group( Api, "Users", (handlers) => handlers.handle("getUsers", () => Effect.succeed( [{ id: 1, name: "User 1" }, { id: 2, name: "User 2" }] )) ) const ApiLayer = HttpApiBuilder.layer(Api).pipe( Layer.provide(GroupLayer), Layer.provide(HttpApiScalar.layer(Api)), HttpRouter.serve, Layer.provide(NodeHttpServer.layer(createServer, { port: 3000 })) ) Layer.launch(ApiLayer).pipe(NodeRuntime.runMain) ``` You can test the endpoint by sending the headers: ```sh curl -H "X-API-Key: 1234567890" -H "X-Request-ID: 1234567890" http://localhost:3000/users ``` The server validates these headers against the declared schema before handling the request. ## Handling Multipart Requests To accept file uploads, mark the payload as multipart with `HttpApiSchema.asMultipart`. Use `Multipart.FilesSchema` for the file fields — uploaded files will be persisted to disk automatically. **Example** (Defining an Endpoint for File Uploads) ```ts import { NodeHttpServer, NodeRuntime } from "@effect/platform-node" import { Effect, Layer, Schema } from "effect" import { HttpRouter, Multipart } from "effect/http" import { HttpApi, HttpApiBuilder, HttpApiEndpoint, HttpApiGroup, HttpApiScalar, HttpApiSchema } from "effect/http-api" import { createServer } from "node:http" const Api = HttpApi.make("MyApi") .add( HttpApiGroup.make("Users") .add( HttpApiEndpoint.post("upload", "/users/upload", { // Specify that the payload is a multipart request payload: HttpApiSchema.asMultipart( Schema.Struct({ // Define a "files" field to handle file uploads files: Multipart.FilesSchema }) ), success: Schema.String }) ) ) const GroupLayer = HttpApiBuilder.group( Api, "Users", (handlers) => handlers .handle("upload", (ctx) => { // ┌─── readonly Multipart.PersistedFile[] // ▼ const { files } = ctx.payload console.log(files) return Effect.succeed("Uploaded") }) ) const ApiLayer = HttpApiBuilder.layer(Api).pipe( Layer.provide(GroupLayer), Layer.provide(HttpApiScalar.layer(Api)), HttpRouter.serve, Layer.provide(NodeHttpServer.layer(createServer, { port: 3000 })) ) Layer.launch(ApiLayer).pipe(NodeRuntime.runMain) ``` You can test this endpoint by sending a multipart request with a file upload. For example: ```sh echo "Sample file content" | curl -X POST -F "files=@-" http://localhost:3000/users/upload ``` ## Changing the Request Encoding By default, request bodies are JSON. To accept a different format — like form-urlencoded data — pipe the payload schema through the appropriate `HttpApiSchema.as*` helper. **Example** (Customizing Request Encoding) ```ts import { NodeHttpServer, NodeRuntime } from "@effect/platform-node" import { Effect, Layer, Schema } from "effect" import { HttpRouter } from "effect/http" import { HttpApi, HttpApiBuilder, HttpApiEndpoint, HttpApiGroup, HttpApiScalar, HttpApiSchema } from "effect/http-api" import { createServer } from "node:http" const User = Schema.Struct({ id: Schema.Int, name: Schema.String }) const Api = HttpApi.make("MyApi") .add( HttpApiGroup.make("Users") .add( HttpApiEndpoint.post("createUser", "/user", { // Set the request payload as a string encoded with query parameters payload: Schema.Struct({ id: Schema.Int, name: Schema.String }) // Specify the encoding as form url encoded .pipe(HttpApiSchema.asFormUrlEncoded()), success: User }) ) ) const GroupLayer = HttpApiBuilder.group( Api, "Users", (handlers) => handlers .handle("createUser", (ctx) => { const user = ctx.payload return Effect.succeed(user) }) ) const ApiLayer = HttpApiBuilder.layer(Api).pipe( Layer.provide(GroupLayer), Layer.provide(HttpApiScalar.layer(Api)), HttpRouter.serve, Layer.provide(NodeHttpServer.layer(createServer, { port: 3000 })) ) Layer.launch(ApiLayer).pipe(NodeRuntime.runMain) ``` You can test this endpoint using a URL-encoded request body. For example: ```sh curl http://localhost:3000/user \ --request POST \ --header 'Accept: */*' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'id=1' \ --data-urlencode 'name=John' ``` ## Accessing the HttpServerRequest Inside a handler, `ctx.request` gives you access to the raw incoming HTTP request. Use this when you need low-level details not covered by the endpoint schema (e.g., the HTTP method or raw URL). **Example** (Accessing the Request Object in a GET Endpoint) ```ts import { NodeHttpServer, NodeRuntime } from "@effect/platform-node" import { Effect, Layer, Schema } from "effect" import { HttpRouter } from "effect/http" import { HttpApi, HttpApiBuilder, HttpApiEndpoint, HttpApiGroup } from "effect/http-api" import { createServer } from "node:http" const Api = HttpApi.make("MyApi").add( HttpApiGroup.make("Greetings").add( HttpApiEndpoint.get("hello", "/", { success: Schema.String }) ) ) const GroupLayer = HttpApiBuilder.group( Api, "Greetings", (handlers) => handlers.handle( "hello", (ctx) => { // ┌─── HttpServerRequest // ▼ const req = ctx.request // Access the request method console.log(req.method) return Effect.succeed("Hello, World!") } ) ) const ApiLayer = HttpApiBuilder.layer(Api).pipe( Layer.provide(GroupLayer), HttpRouter.serve, Layer.provide(NodeHttpServer.layer(createServer, { port: 3000 })) ) Layer.launch(ApiLayer).pipe(NodeRuntime.runMain) ``` ## Validating Request Cookies There is no `cookies` option on endpoints. Instead, validated cookie access goes through the security middleware system: define an `HttpApiSecurity.apiKey` with `in: "cookie"` and attach it to a middleware. The cookie value is decoded and handed to your security handler as a `Redacted` credential. **Example** (Validating a Session Cookie) ```ts import { NodeHttpServer, NodeRuntime } from "@effect/platform-node" import { Context, Effect, Layer, Redacted, Schema } from "effect" import { HttpRouter } from "effect/http" import { HttpApi, HttpApiBuilder, HttpApiEndpoint, HttpApiGroup, HttpApiMiddleware, HttpApiScalar, HttpApiSecurity } from "effect/http-api" import { createServer } from "node:http" // Define the service providing the current user class CurrentUser extends Context.Service()("CurrentUser") {} // Define the security scheme: read the "session" cookie const sessionCookie = HttpApiSecurity.apiKey({ in: "cookie", key: "session" }) class Auth extends HttpApiMiddleware.Service()("Auth", { error: Schema.String.annotate({ httpApiStatus: 401, description: "Auth error" }), security: { session: sessionCookie } }) {} const Api = HttpApi.make("api").add( HttpApiGroup.make("group") .add( HttpApiEndpoint.get("me", "/me", { success: Schema.Struct({ id: Schema.Finite }) }) ) .middleware(Auth) ) const AuthLayer = Layer.succeed( Auth, { session: (effect, opts) => Effect.provideServiceEffect( effect, CurrentUser, Effect.gen(function*() { const value = Redacted.value(opts.credential) if (value !== "valid-session") { return yield* Effect.fail("Invalid session") } return { id: 1, name: "John Doe" } }) ) } ) const GroupLayer = HttpApiBuilder.group( Api, "group", (handlers) => handlers.handle("me", () => Effect.gen(function*() { const user = yield* CurrentUser return { id: user.id } })) ).pipe(Layer.provide(AuthLayer)) const ApiLayer = HttpApiBuilder.layer(Api).pipe( Layer.provide(GroupLayer), Layer.provide(HttpApiScalar.layer(Api)), HttpRouter.serve, Layer.provide(NodeHttpServer.layer(createServer, { port: 3000 })) ) Layer.launch(ApiLayer).pipe(NodeRuntime.runMain) // Valid session: // curl "http://localhost:3000/me" --cookie "session=valid-session" // {"id":1} // // Invalid session: // curl "http://localhost:3000/me" --cookie "session=wrong" // "Invalid session" ``` For quick, unvalidated access you can read cookies directly from `ctx.request.cookies` inside any handler. These cookies won't appear in the OpenAPI spec. **Example** (Reading Cookies Directly in a Handler) ```ts import { NodeHttpServer, NodeRuntime } from "@effect/platform-node" import { Effect, Layer, Schema } from "effect" import { HttpRouter } from "effect/http" import { HttpApi, HttpApiBuilder, HttpApiEndpoint, HttpApiGroup } from "effect/http-api" import { createServer } from "node:http" const Api = HttpApi.make("api").add( HttpApiGroup.make("group").add( HttpApiEndpoint.get("me", "/me", { success: Schema.String }) ) ) const GroupLayer = HttpApiBuilder.group( Api, "group", (handlers) => handlers.handle("me", (ctx) => { const lang = ctx.request.cookies.lang ?? "en" return Effect.succeed(`Language: ${lang}`) }) ) const ApiLayer = HttpApiBuilder.layer(Api).pipe( Layer.provide(GroupLayer), HttpRouter.serve, Layer.provide(NodeHttpServer.layer(createServer, { port: 3000 })) ) Layer.launch(ApiLayer).pipe(NodeRuntime.runMain) // curl "http://localhost:3000/me" --cookie "lang=it" // "Language: it" ``` ## Streaming Requests To receive large or continuous uploads, declare the payload with a streaming schema. These are the same constructors used for [streaming responses](#streaming-responses), and the slot decides the direction: | Declaration | Handler receives | Default content type | | ----------------------------------------------------------------------------------- | --------------------------------------------------------- | -------------------------- | | `HttpApiSchema.StreamUint8Array({ contentType?, maxBytes? })` | `Stream` | `application/octet-stream` | | `HttpApiSchema.StreamNdjson({ schema, contentType?, maxBytes?, maxElementBytes? })` | `Stream` | `application/x-ndjson` | The handler gets a lazy `Stream`. The server reads the socket only as the handler pulls, with no read-ahead, so not pulling is the backpressure. `HttpApiSchema.StreamSse` is response-only and is rejected in `payload`. ### Streaming Raw Bytes **Example** (Receiving a Binary Upload) ```ts import { NodeHttpServer, NodeRuntime } from "@effect/platform-node" import { Effect, Layer, Schema, Stream } from "effect" import { HttpRouter } from "effect/http" import { HttpApi, HttpApiBuilder, HttpApiEndpoint, HttpApiGroup, HttpApiSchema } from "effect/http-api" import { createServer } from "node:http" const Api = HttpApi.make("myApi").add( HttpApiGroup.make("group").add( HttpApiEndpoint.post("upload", "/upload", { // Stream the body as raw bytes and stop after 100 MiB // (default content type: application/octet-stream) payload: HttpApiSchema.StreamUint8Array({ maxBytes: "100 MiB" }), success: Schema.String }) ) ) const GroupLayer = HttpApiBuilder.group( Api, "group", (handlers) => handlers.handle("upload", ({ payload }) => // payload: Stream payload.pipe( // The body is read as the fold pulls, never buffered as a whole Stream.runFold(() => 0, (total, chunk) => total + chunk.length), Effect.map((total) => `received ${total} bytes`) )) ) const ApiLayer = HttpApiBuilder.layer(Api).pipe( Layer.provide(GroupLayer), HttpRouter.serve, Layer.provide(NodeHttpServer.layer(createServer, { port: 3000 })) ) Layer.launch(ApiLayer).pipe(NodeRuntime.runMain) // printf 'abc' | curl -X POST 'http://localhost:3000/upload' --data-binary @- -H "Content-Type: application/octet-stream" // "received 3 bytes" ``` ### Streaming NDJSON `HttpApiSchema.StreamNdjson({ schema })` declares a body of newline-delimited JSON, one encoded element per line. The handler receives decoded elements, and the element schema's decoding services are added to the handler's requirements. **Example** (Importing Records Line by Line) ```ts import { NodeHttpServer, NodeRuntime } from "@effect/platform-node" import { Effect, Layer, Schema, Stream } from "effect" import { HttpRouter } from "effect/http" import { HttpApi, HttpApiBuilder, HttpApiEndpoint, HttpApiGroup, HttpApiSchema } from "effect/http-api" import { createServer } from "node:http" const Event = Schema.Struct({ id: Schema.Number, name: Schema.String }) const Api = HttpApi.make("myApi").add( HttpApiGroup.make("group").add( HttpApiEndpoint.post("importEvents", "/events", { // One JSON-encoded Event per line // (default content type: application/x-ndjson) payload: HttpApiSchema.StreamNdjson({ schema: Event }), success: Schema.String }) ) ) const GroupLayer = HttpApiBuilder.group( Api, "group", (handlers) => handlers.handle("importEvents", ({ payload }) => { // payload: Stream let accepted = 0 return payload.pipe( Stream.runForEach((_event) => Effect.sync(() => { // store the event... accepted++ }) ), Effect.map(() => `accepted ${accepted} records`), // A bad record ends the stream. Every record before it has already // been handled, so report how far the import got Effect.catchTag("HttpApiSchemaError", () => Effect.succeed(`accepted ${accepted} records, record ${accepted + 1} is invalid`)) // HttpApiPayloadTooLarge is not caught, so it becomes an empty 413 ) }) ) const ApiLayer = HttpApiBuilder.layer(Api).pipe( Layer.provide(GroupLayer), HttpRouter.serve, Layer.provide(NodeHttpServer.layer(createServer, { port: 3000 })) ) Layer.launch(ApiLayer).pipe(NodeRuntime.runMain) // printf '{"id":1,"name":"a"}\n{"id":2,"name":"b"}\nnope\n' | curl -X POST 'http://localhost:3000/events' --data-binary @- -H "Content-Type: application/x-ndjson" // "accepted 2 records, record 3 is invalid" ``` The wire format: - The server accepts only the declared content types, compared after normalization, and answers `415` otherwise. To also accept JSON Lines, pass a list such as `contentType: ["application/x-ndjson", "application/jsonl"]`. The derived client sends the first entry. - `\n`, `\r\n` and a bare `\r` each end a line. Empty lines are skipped, so a client can send `\n` as a keep-alive. A line containing only whitespace is malformed. - A missing final newline is fine if the last line parses. If it doesn't, the issue message says "unterminated final line", so a truncated body is recognizable. - A leading UTF-8 BOM is stripped. Invalid UTF-8 is an error, never replaced with U+FFFD. - The first malformed line, or the first element that fails to decode, fails the stream with an `HttpApiSchemaError` (`kind: "Payload"`), after every element before it has been delivered. A failure ends the stream, so a handler can't skip a bad record and keep reading. To skip bad records, declare a lenient element schema and filter. - NDJSON can't detect a body that was cut cleanly at a line boundary. It looks like a shorter, complete body. ### Limits and Errors Limits are set on the declaration only: - `maxBytes` caps the whole body. It has no default, and it does not fall back to `MaxBodySize`, which only applies to buffered reads. - `maxElementBytes` (NDJSON only) caps the UTF-8 bytes of one line, without its terminator. It defaults to 1 MiB, and a longer line fails before the rest of it is buffered. - Both count the bytes the handler sees, after the `HttpMiddleware.decompression` middleware. - Both count only bytes that are actually read. After `Stream.take(1)`, `maxBytes` never fires. If the request's `content-length` exceeds `maxBytes`, the server answers an empty `413` with `Connection: close` as soon as params, headers and query have decoded. The handler doesn't run and no body byte is read. The payload stream's errors are added to the handler's error channel automatically. A handler can catch them after a partial read, as in the example above, or let them through. The server maps the ones it lets through before responding: | Error | Response | | ---------------------------- | ------------------------------------ | | `HttpApiSchemaError` | `400`, the same as buffered payloads | | `HttpApiPayloadTooLarge` | empty `413` | | Body read failure (a defect) | `500`, reported | `HttpApiPayloadTooLarge` carries `limit` (`"maxBytes"` or `"maxElementBytes"`) and its configured `size`. `HttpMiddleware.decompression` also caps the decompressed body at `maxDecompressedSize`, which defaults to `MaxBodySize` and then to 10 MiB. That cap applies to streaming payloads too, and breaching it answers `413`. Raise `maxDecompressedSize` on servers that accept large compressed uploads. ### Body Lifetime - Middleware runs first, then params, headers and query, then the payload. A params, headers or query failure answers `400` without reading a body byte, and the handler always gets the body unread. - Read the payload stream once. The body is never buffered for a replay, so a repeated read keeps the adapter's native behavior: an empty body, a typed `RequestParseError`, or a replay of the caller's stream under `HttpApiTest`. Don't rely on any of them. - A handler can respond without reading the whole body, for example to reject an upload early. Over HTTP/1.1 the Node server then drains up to 256 KiB of what is left. Past that it sends `Connection: close` and closes the socket. ### Timing Out Request Bodies Effect puts no deadline on reading a request body. Bound the read with Effect timeouts: - For a streaming payload, use `Stream.timeoutOrElse` to fail the read when the client stops sending. `Stream.timeout` would end the stream instead, so a stalled upload would look complete to the handler. - For a buffered payload, add a middleware with `Effect.timeoutOrElse`. Middleware runs around payload decoding (see [Body Lifetime](#body-lifetime)), so its deadline covers receiving and decoding the body as well as the handler. **Example** (Timing Out Uploads) ```ts import { Effect, Layer, Schema, Stream } from "effect" import { HttpApi, HttpApiBuilder, HttpApiEndpoint, HttpApiError, HttpApiGroup, HttpApiMiddleware, HttpApiSchema } from "effect/http-api" // Answers 408 when the endpoint, payload decoding included, takes too long class Deadline extends HttpApiMiddleware.Service()("Deadline", { error: HttpApiError.RequestTimeout }) {} const Api = HttpApi.make("api").add( HttpApiGroup.make("files").add( HttpApiEndpoint.post("upload", "/upload", { payload: HttpApiSchema.StreamUint8Array(), success: Schema.Number, error: HttpApiError.RequestTimeout }), HttpApiEndpoint.post("import", "/import", { payload: Schema.Array(Schema.String), success: Schema.Number }).middleware(Deadline) ) ) const DeadlineLayer = Layer.succeed( Deadline, (httpEffect) => Effect.timeoutOrElse(httpEffect, { duration: "30 seconds", orElse: () => Effect.fail(new HttpApiError.RequestTimeout({})) }) ) const FilesLayer = HttpApiBuilder.group( Api, "files", (handlers) => handlers .handle("upload", ({ payload }) => payload.pipe( // Fail the read when the client sends nothing for 10 seconds Stream.timeoutOrElse({ duration: "10 seconds", orElse: () => Stream.fail(new HttpApiError.RequestTimeout({})) }), Stream.runFold(() => 0, (total, chunk) => total + chunk.length) )) .handle("import", ({ payload }) => Effect.succeed(payload.length)) ).pipe(Layer.provide(DeadlineLayer)) ``` When a timeout interrupts a handler before it has read the whole body, the unread rest is handled as described in [Body Lifetime](#body-lifetime). A middleware deadline stops applying once the handler returns a streaming response. To bound the response, see [Timing Out Streaming Responses](#timing-out-streaming-responses). The runtimes also have their own server-wide timers: - Node's `requestTimeout` (300 seconds by default) limits the time to receive the whole request, including a streaming upload. When it expires, Node answers `408`, or closes the connection if the response has already started. It also applies to a request body the handler never reads, so it can cut a streaming response that ignores a large upload. Change it on the server you pass to `NodeHttpServer.layer`. `0` disables it. - Node's `headersTimeout` (60 seconds by default) limits the time to receive the headers. When it is not set, Node lowers it to `requestTimeout` if that is smaller, so `createServer({ requestTimeout: 0 })` disables the header deadline too. Use `createServer({ requestTimeout: 0, headersTimeout: 60_000 })` to keep it. When both are nonzero, `headersTimeout` may not exceed `requestTimeout`. - `BunHttpServer` disables Bun's idle timeout by default, so a slow upload is limited only by your own timeouts. Pass `idleTimeout` (in seconds, at most 255) to restore a cut for connections that stay silent that long. ### Mixing Buffered and Streaming Payloads One streaming payload can share the `payload` array with buffered payloads that use other content types. The server picks one by the request's content type, and the handler tells them apart with `Stream.isStream`. **Example** (Accepting a JSON Array or an NDJSON Stream) ```ts import { Effect, Schema, Stream } from "effect" import { HttpApi, HttpApiBuilder, HttpApiEndpoint, HttpApiGroup, HttpApiSchema } from "effect/http-api" const Event = Schema.Struct({ id: Schema.Number, name: Schema.String }) const Api = HttpApi.make("myApi").add( HttpApiGroup.make("group").add( HttpApiEndpoint.post("importEvents", "/events", { payload: [ // application/json: the whole batch in one body Schema.Array(Event), // application/x-ndjson: one event per line, streamed HttpApiSchema.StreamNdjson({ schema: Event }) ], success: Schema.Number }) ) ) const GroupLayer = HttpApiBuilder.group( Api, "group", (handlers) => handlers.handle("importEvents", ({ payload }) => Stream.isStream(payload) ? Stream.runCount(payload) : Effect.succeed(payload.length)) ) ``` Endpoint construction throws when: - two streaming payloads are declared, because the client could not choose an encoding for a `Stream` - a streaming and a buffered payload share a media type, compared after normalization, so `; charset=utf-8` does not make them distinct - the method is `GET`, `HEAD`, `OPTIONS` or `TRACE`, which is also a type error. Every other method, including `DELETE` and `QUERY`, accepts a streaming payload ### Sending Streams with the Derived Client The derived client takes a `Stream` as the payload: `Stream` for `StreamUint8Array`, and `Stream` for `StreamNdjson`. It sends the stream as it is pulled, without buffering, with the declared content type and no `content-length`. NDJSON elements are encoded lazily, each as one line of JSON followed by `\n`. The method infers only `R` from the stream, plus the services the element schema needs to encode. The stream's error isn't one of the endpoint's declared errors, so it's not in the method's type. A failing source aborts the upload, and the method fails with the `HttpClientError` the adapter reports. If the source fails while a streaming success response is being read, the response stream fails with that `HttpClientError` instead. An element that fails to encode fails the upload the same way. **Example** (Uploading a Stream of Records) ```ts import { Effect, Schema, Stream } from "effect" import { FetchHttpClient } from "effect/http" import { HttpApi, HttpApiClient, HttpApiEndpoint, HttpApiGroup, HttpApiSchema } from "effect/http-api" const Event = Schema.Struct({ id: Schema.Number, name: Schema.String }) const Api = HttpApi.make("myApi").add( HttpApiGroup.make("group").add( HttpApiEndpoint.post("importEvents", "/events", { payload: HttpApiSchema.StreamNdjson({ schema: Event }), success: Schema.String }) ) ) const program = Effect.gen(function*() { const client = yield* HttpApiClient.make(Api, { baseUrl: "http://localhost:3000" }) // Any Stream of Events works const events = Stream.range(1, 1000).pipe( Stream.map((id) => ({ id, name: `event ${id}` })) ) const result = yield* client.group.importEvents({ payload: events }) console.log(result) }) // program: Effect Effect.runFork(program.pipe(Effect.provide(FetchHttpClient.layer))) ``` Things to know: - A `400` or `413` from the server is an `HttpClientError` with a `DecodeError` reason, as a buffered `400` is today. There's no client-side `HttpApiPayloadTooLarge`, because the `413` body is empty. - The client doesn't check `maxBytes` or `maxElementBytes` before sending. A `HttpClient.mapRequest` that sets `content-length` lets the server answer an early `413` on Node clients. `FetchHttpClient` strips `content-length`. - With a streaming success response, the upload runs until either side ends. Otherwise it's interrupted once the method has decoded the response, whether that's an error status or a buffered success. - Retries and redirects replay the stream. `HttpClient.retry` and 307/308 redirects run the payload stream again. That's right for a source that can be re-read, like a file, and wrong for a one-shot source like `Stream.fromQueue`: a retry would send only what is left in the queue. Don't retry uploads from such sources, or buffer them first. - On a mixed payload, a `Stream` value is always sent with the streaming member, even when a buffered member's `Type` would also accept it (`Schema.Unknown`, `Schema.Any`). A `Uint8Array` or an array is never wrapped into a stream. - `FetchHttpClient` needs a runtime that can send a `ReadableStream` request body. Node, Bun and Deno can. In browsers, Chrome sends streaming uploads only over HTTP/2 or later, and over HTTP/1.1 the request fails with a `TransportError`. ### Streaming Both Ways A streaming payload can be combined with a streaming success response. Neither direction is buffered, and response headers go out as soon as the handler returns its stream. **Example** (Transforming an Upload as It Arrives) ```ts import { Effect, Schema, Stream } from "effect" import { HttpApi, HttpApiBuilder, HttpApiEndpoint, HttpApiGroup, HttpApiSchema } from "effect/http-api" const Event = Schema.Struct({ id: Schema.Number, name: Schema.String }) const Api = HttpApi.make("myApi").add( HttpApiGroup.make("group").add( HttpApiEndpoint.post("enrich", "/enrich", { payload: HttpApiSchema.StreamNdjson({ schema: Event }), success: HttpApiSchema.StreamNdjson({ schema: Event }) }), HttpApiEndpoint.post("enrichBatch", "/enrich-batch", { payload: HttpApiSchema.StreamNdjson({ schema: Event }), success: HttpApiSchema.StreamNdjson({ schema: Event }) }) ) ) const enrich = (event: typeof Event.Type) => ({ ...event, name: event.name.toUpperCase() }) const GroupLayer = HttpApiBuilder.group( Api, "group", (handlers) => handlers // Interleaved: each output line is written as its input line arrives. // Needs a full-duplex client .handle("enrich", ({ payload }) => Effect.succeed(Stream.map(payload, enrich))) // Portable: read the whole upload, then respond .handle("enrichBatch", ({ payload }) => Stream.runCollect(payload).pipe( Effect.map((events) => Stream.fromIterable(events.map(enrich))) )) ) ``` Interleaving is best effort, and both ends must be full duplex. Node's `node:http` and undici, and Bun's and Deno's `fetch`, are. Browsers send uploads with `duplex: "half"` and don't read the response until the upload has ended. A handler that pipes its input to its output, like `enrich` above, then deadlocks once the data outgrows the flow-control windows. The portable pattern is the one `enrichBatch` uses: consume the upload, then respond. Once the response headers are sent, the payload stream is pulled inside the response stream. A payload failure is then a response failure: the connection is aborted and the client sees a body read error. For a `StreamSse` response, map the payload error into the declared SSE `error` schema to send it as a typed failure. On Deno, an HTTP/1.1 request body read can stall while the handler returns a streamed response (denoland/deno#36966), which affects this pattern until the fix ships. ### Proxying a Streaming Upload `HttpServerRequest.toClientRequest` turns the incoming request into an outbound `HttpClientRequest` that streams the same body. The body is not buffered, so if the outbound client retries the proxied request or follows a 307/308 redirect, the retry resends whatever the adapter gives a second read, usually an empty body. A proxy that retries has to buffer the body itself, or turn retries off. ### Testing with HttpApiTest `HttpApiTest` passes a `Stream` payload to the handler unbuffered, pulling each element from the caller's stream as the handler reads it. Limits, the `400` and both `413` paths work in memory. The early `413` needs a `content-length`, which the client doesn't send for streams, so set one through `HttpClient.mapRequest`. When the caller's stream fails, the handler's read of the payload fails as a defect and the test call dies with it, because `HttpApiTest` doesn't turn defects into responses. Inside a streaming response, the response body fails instead. Socket behavior and client aborts are not emulated: no draining of unread bodies, no `Connection: close`, no interrupted handler, and no `499`. ### Reading the Raw Request Body To take over body handling completely, register the endpoint with `.handleRaw`. It opts out of automatic payload decoding and exposes the raw `HttpServerRequest`, whose body is available as a `Stream` of `Uint8Array` chunks through `request.stream`. The payload schema still describes the endpoint in the generated documentation, but with `.handleRaw` the handler decides how the body is consumed. The declared content type is no longer enforced at runtime: requests with a different `Content-Type` header are not rejected with `415`, so any such validation is up to the handler. **Example** (Reading the Raw Request Body) ```ts import { NodeHttpServer, NodeRuntime } from "@effect/platform-node" import { Effect, Layer, Schema, Stream } from "effect" import { HttpRouter } from "effect/http" import { HttpApi, HttpApiBuilder, HttpApiEndpoint, HttpApiGroup, HttpApiSchema } from "effect/http-api" import { createServer } from "node:http" const Api = HttpApi.make("myApi").add( HttpApiGroup.make("group").add( HttpApiEndpoint.post("acceptStream", "/stream", { // Define the payload as a Uint8Array with a specific encoding payload: Schema.Uint8Array.pipe( HttpApiSchema.asUint8Array() // default content type: application/octet-stream ), success: Schema.String }) ) ) const GroupLayer = HttpApiBuilder.group( Api, "group", (handlers) => // Use `handleRaw` to opt out of payload decoding and access the raw request handlers.handleRaw("acceptStream", (ctx) => // Consume the request body as a stream of Uint8Array chunks ctx.request.stream.pipe( // Fold over the chunks as they arrive, without buffering the body Stream.runFold(() => 0, (total, chunk) => total + chunk.length), Effect.map((total) => `received ${total} bytes`), // `request.stream` fails with `HttpServerError`, which the endpoint // does not declare, so treat it as a defect Effect.orDie )) ) const ApiLayer = HttpApiBuilder.layer(Api).pipe( Layer.provide(GroupLayer), HttpRouter.serve, Layer.provide(NodeHttpServer.layer(createServer, { port: 3000 })) ) Layer.launch(ApiLayer).pipe(NodeRuntime.runMain) ``` You can test the streaming request using `curl` or any tool that supports sending binary data. For example: ```sh printf 'abc' | curl -X POST 'http://localhost:3000/stream' --data-binary @- -H "Content-Type: application/octet-stream" # Output: "received 3 bytes" ``` # Response ## Status Codes Success responses default to `200 OK`. To use a different status code, annotate the success schema with `HttpApiSchema.status(code)` or set the `httpApiStatus` annotation. **Example** (Defining a GET Endpoint with a custom status code) ```ts import { NodeHttpServer, NodeRuntime } from "@effect/platform-node" import { Effect, Layer, Schema } from "effect" import { HttpRouter } from "effect/http" import { HttpApi, HttpApiBuilder, HttpApiEndpoint, HttpApiGroup, HttpApiScalar, HttpApiSchema } from "effect/http-api" import { createServer } from "node:http" const User = Schema.Struct({ id: Schema.Int, name: Schema.String }) const Api = HttpApi.make("MyApi") .add( HttpApiGroup.make("Users") .add( HttpApiEndpoint.get("getUsers", "/users", { success: Schema.Array(User) .pipe(HttpApiSchema.status(206)) }) ) ) const GroupLayer = HttpApiBuilder.group( Api, "Users", (handlers) => handlers .handle("getUsers", () => { return Effect.succeed( [{ id: 1, name: "User 1" }, { id: 2, name: "User 2" }] ) }) ) const ApiLayer = HttpApiBuilder.layer(Api).pipe( Layer.provide(GroupLayer), Layer.provide(HttpApiScalar.layer(Api)), HttpRouter.serve, Layer.provide(NodeHttpServer.layer(createServer, { port: 3000 })) ) Layer.launch(ApiLayer).pipe(NodeRuntime.runMain) ``` ## Changing the Response Encoding Responses default to JSON. To return a different format — like CSV or plain text — pipe the success schema through the matching `HttpApiSchema.as*` helper and, optionally, set a custom `contentType`. **Example** (Returning Data as `text/csv`) ```ts import { NodeHttpServer, NodeRuntime } from "@effect/platform-node" import { Effect, Layer, Schema } from "effect" import { HttpRouter } from "effect/http" import { HttpApi, HttpApiBuilder, HttpApiEndpoint, HttpApiGroup, HttpApiScalar, HttpApiSchema } from "effect/http-api" import { createServer } from "node:http" const Api = HttpApi.make("MyApi") .add( HttpApiGroup.make("Users") .add( HttpApiEndpoint.get("csv", "/users/csv", { success: Schema.String.pipe( // Set the success response as a string with CSV encoding HttpApiSchema.asText({ // Define the content type as text/csv contentType: "text/csv" }) ) }) ) ) const GroupLayer = HttpApiBuilder.group( Api, "Users", (handlers) => handlers .handle("csv", (ctx) => { return Effect.succeed("id,name\n1,John\n2,Jane") }) ) const ApiLayer = HttpApiBuilder.layer(Api).pipe( Layer.provide(GroupLayer), Layer.provide(HttpApiScalar.layer(Api)), HttpRouter.serve, Layer.provide(NodeHttpServer.layer(createServer, { port: 3000 })) ) Layer.launch(ApiLayer).pipe(NodeRuntime.runMain) ``` You can test this endpoint using a GET request. For example: ```sh curl http://localhost:3000/users/csv ``` The following encodings are supported: - `Json` the default encoding (default content type: `application/json`) - `Uint8Array` the encoding for binary data (default content type: `application/octet-stream`) - `Text` the encoding for text data (default content type: `text/plain`) ## Setting Response Headers Response headers can be declared in the endpoint's schemas, so they are type-checked on the server, rendered in the OpenAPI documentation, and decoded by the derived client. Two mechanisms are available: - `HttpApiSchema.WithHeaders(schema, headers)` wraps a response schema together with a headers schema. Handlers return the body and headers as a pair. Recommended for success responses, including streams. - `HttpApiSchema.encodeToWithHeaders` folds headers into an opaque domain type such as an error class, so handlers keep working with plain domain values. Only one response schema carrying headers may be declared for each status, though plain responses with different content types may share that status. For headers that are not part of the API contract, `HttpEffect.appendPreResponseHandler` remains available as an untyped escape hatch. ### Declaring Response Headers with WithHeaders Wrap the success schema with `HttpApiSchema.WithHeaders(schema, headers)`. The headers argument accepts a fields shorthand (as below) or any schema, mirroring the request-side `headers` option. The handler then returns a value built with `HttpApiSchema.withHeaders({ body, headers })`. **Example** (Declaring a Response Header on a Success Schema) ```ts import { NodeHttpServer, NodeRuntime } from "@effect/platform-node" import { Effect, Layer, Schema } from "effect" import { HttpRouter } from "effect/http" import { HttpApi, HttpApiBuilder, HttpApiEndpoint, HttpApiGroup, HttpApiSchema } from "effect/http-api" import { createServer } from "node:http" const User = Schema.Struct({ id: Schema.Int, name: Schema.String }) const Api = HttpApi.make("MyApi").add( HttpApiGroup.make("Users").add( HttpApiEndpoint.get("getUsers", "/users", { // Wrap the success schema with a response headers schema success: HttpApiSchema.WithHeaders(Schema.Array(User), { "x-total-count": Schema.Int }) }) ) ) const GroupLayer = HttpApiBuilder.group( Api, "Users", (handlers) => handlers.handle("getUsers", () => // Return the body together with the declared headers Effect.succeed(HttpApiSchema.withHeaders({ body: [{ id: 1, name: "John" }], headers: { "x-total-count": 1 } }))) ) const ApiLayer = HttpApiBuilder.layer(Api).pipe( Layer.provide(GroupLayer), HttpRouter.serve, Layer.provide(NodeHttpServer.layer(createServer, { port: 3000 })) ) Layer.launch(ApiLayer).pipe(NodeRuntime.runMain) // curl -v "http://localhost:3000/users" 2>&1 | grep -i "x-total-count" // < x-total-count: 1 ``` The derived client detects the wrapper and returns the same shape, with the headers decoded through the headers schema: ```ts const users = yield * client.Users.getUsers() users.body // => [{ id: 1, name: "John" }] users.headers // => { "x-total-count": 1 } ``` Things to know: - Header values are converted to strings at the HTTP boundary, the same way as request headers, params, and query. `Schema.Int` goes out as `"1"` and decodes back to `1` on the client. `undefined` values are omitted from the response. - Status and encoding annotations resolve from the wrapper first, then fall through to the inner schema, so `HttpApiSchema.WithHeaders(User.pipe(HttpApiSchema.status(201)), ...)` responds with `201`. - Declared headers are applied after the body is encoded and override headers set by the encoding on collision, including `content-type`. - Stream success schemas (`HttpApiSchema.StreamSse`, `HttpApiSchema.StreamUint8Array`) can be wrapped too. Headers are encoded before the response starts streaming, and the client resolves to a value whose `body` is the stream. - `WithHeaders` is also allowed on error schemas, in which case the handler fails with the wrapped value. For errors, `encodeToWithHeaders` (below) is usually more convenient because handlers can fail with the domain error directly. ### Folding Headers into Domain Types with encodeToWithHeaders `HttpApiSchema.encodeToWithHeaders` encodes a schema as a `{ body, headers }` pair while its Type stays unchanged. This lets an error class carry data that travels in a response header: handlers fail with plain error instances, and the client receives the same class with the header folded back in. The body schema is authoritative for everything wire-level: status, content type, and response encoding resolve from the body schema's annotations. A status annotation on the source schema stops mattering once wrapped, so spell the status on the body — `HttpApiSchema.Empty(404)` declares an empty body with status 404. **Example** (Returning an Error With a Response Header) ```ts import { NodeHttpServer, NodeRuntime } from "@effect/platform-node" import { Effect, Layer, Schema } from "effect" import { HttpRouter } from "effect/http" import { HttpApi, HttpApiBuilder, HttpApiEndpoint, HttpApiGroup, HttpApiSchema } from "effect/http-api" import { createServer } from "node:http" class UserNotFound extends Schema.TaggedError()("UserNotFound", { userId: Schema.Int }) {} const UserNotFoundWithHeaders = UserNotFound.pipe( HttpApiSchema.encodeToWithHeaders({ // The body schema is authoritative for status and content type body: HttpApiSchema.Empty(404), headers: { "x-user-id": Schema.Int } }, { // Pure mappings between the domain type and the { body, headers } pair decode: ({ headers }) => new UserNotFound({ userId: headers["x-user-id"] }), encode: (error) => ({ headers: { "x-user-id": error.userId }, body: undefined }) }) ) const User = Schema.Struct({ id: Schema.Int, name: Schema.String }) const Api = HttpApi.make("MyApi").add( HttpApiGroup.make("Users").add( HttpApiEndpoint.get("getUser", "/user/:id", { params: { id: Schema.Int }, success: User, error: UserNotFoundWithHeaders }) ) ) const GroupLayer = HttpApiBuilder.group( Api, "Users", (handlers) => handlers.handle("getUser", (ctx) => { const id = ctx.params.id if (id === 1) { // Fail with the plain error instance return Effect.fail(new UserNotFound({ userId: id })) } return Effect.succeed({ id, name: `User ${id}` }) }) ) const ApiLayer = HttpApiBuilder.layer(Api).pipe( Layer.provide(GroupLayer), HttpRouter.serve, Layer.provide(NodeHttpServer.layer(createServer, { port: 3000 })) ) Layer.launch(ApiLayer).pipe(NodeRuntime.runMain) // curl -v "http://localhost:3000/user/1" 2>&1 | grep -i "x-user-id" // < x-user-id: 1 ``` The `decode`/`encode` mappings are pure total functions: validation lives in the body and headers schemas, the mappings only reshape valid data. The error channel is unchanged — a client calling this endpoint fails with a `UserNotFound` instance whose `userId` was decoded from the header. `encodeToWithHeaders` also works on custom success types, but avoid burying stream schemas in it; wrap streams with `WithHeaders` instead so the generated client keeps the stream's error channel. ### Untyped Response Headers For headers that should not appear in the API contract, call `HttpEffect.appendPreResponseHandler` inside your handler. The callback receives the request and response objects and must return the updated response. These headers bypass the schemas, the OpenAPI documentation, and the derived client. **Example** (Adding a Custom Response Header) ```ts import { NodeHttpServer, NodeRuntime } from "@effect/platform-node" import { Effect, Layer, Schema } from "effect" import { HttpEffect, HttpRouter, HttpServerResponse } from "effect/http" import { HttpApi, HttpApiBuilder, HttpApiEndpoint, HttpApiGroup } from "effect/http-api" import { createServer } from "node:http" const Api = HttpApi.make("api").add( HttpApiGroup.make("group").add( HttpApiEndpoint.get("hello", "/hello", { success: Schema.String }) ) ) const GroupLayer = HttpApiBuilder.group( Api, "group", (handlers) => handlers.handle("hello", () => Effect.gen(function*() { yield* HttpEffect.appendPreResponseHandler((_req, response) => Effect.succeed(HttpServerResponse.setHeader(response, "x-custom", "hello")) ) return "Hello, World!" })) ) const ApiLayer = HttpApiBuilder.layer(Api).pipe( Layer.provide(GroupLayer), HttpRouter.serve, Layer.provide(NodeHttpServer.layer(createServer, { port: 3000 })) ) Layer.launch(ApiLayer).pipe(NodeRuntime.runMain) // curl -v "http://localhost:3000/hello" 2>&1 | grep -i "x-custom" // < x-custom: hello ``` ## Setting Response Cookies Set cookies on the response using `HttpEffect.appendPreResponseHandler` together with `HttpServerResponse.setCookie`. For cookies tied to an `HttpApiSecurity.apiKey`, use the shortcut `HttpApiBuilder.securitySetCookie` instead. **Example** (Setting a Response Cookie) ```ts import { NodeHttpServer, NodeRuntime } from "@effect/platform-node" import { Effect, Layer, Schema } from "effect" import { HttpEffect, HttpRouter, HttpServerResponse } from "effect/http" import { HttpApi, HttpApiBuilder, HttpApiEndpoint, HttpApiGroup } from "effect/http-api" import { createServer } from "node:http" const Api = HttpApi.make("api").add( HttpApiGroup.make("group").add( HttpApiEndpoint.get("hello", "/hello", { success: Schema.String }) ) ) const GroupLayer = HttpApiBuilder.group( Api, "group", (handlers) => handlers.handle("hello", () => Effect.gen(function*() { yield* HttpEffect.appendPreResponseHandler((_req, response) => Effect.succeed(HttpServerResponse.setCookieUnsafe(response, "my-cookie", "my-value", { httpOnly: true, secure: true, path: "/" })) ) return "Hello, World!" })) ) const ApiLayer = HttpApiBuilder.layer(Api).pipe( Layer.provide(GroupLayer), HttpRouter.serve, Layer.provide(NodeHttpServer.layer(createServer, { port: 3000 })) ) Layer.launch(ApiLayer).pipe(NodeRuntime.runMain) // curl -v "http://localhost:3000/hello" 2>&1 | grep -i "set-cookie" // < set-cookie: my-cookie=my-value; Path=/; HttpOnly; Secure ``` ## Redirects To redirect the client to a different URL, return an `HttpServerResponse.redirect` from the handler. The redirect is not modeled in the schema — the endpoint definition stays as "no content". ```ts import { NodeHttpServer, NodeRuntime } from "@effect/platform-node" import { Effect, Layer, Schema } from "effect" import { HttpRouter } from "effect/http" import { HttpServerResponse } from "effect/http" import { HttpApi, HttpApiBuilder, HttpApiEndpoint, HttpApiGroup, HttpApiScalar } from "effect/http-api" import { createServer } from "node:http" const Api = HttpApi.make("MyApi").add( HttpApiGroup.make("group").add( HttpApiEndpoint.get("newPage", "/new", { success: Schema.String }), // Schema-wise this is just "no content" (redirect headers aren't modeled here) HttpApiEndpoint.get("oldPage", "/old") ) ) const GroupLayer = HttpApiBuilder.group( Api, "group", (handlers) => handlers.handleAll({ newPage: () => Effect.succeed("You are on /new"), oldPage: () => Effect.succeed( HttpServerResponse.redirect("/new", { status: 302 }) ) }) ) const ApiLayer = HttpApiBuilder.layer(Api).pipe( Layer.provide(GroupLayer), Layer.provide(HttpApiScalar.layer(Api)), HttpRouter.serve, Layer.provide(NodeHttpServer.layer(createServer, { port: 3000 })) ) Layer.launch(ApiLayer).pipe(NodeRuntime.runMain) // curl "http://localhost:3000/old" -L ``` ## Streaming Responses To stream data to the client over time, declare the success schema with one of the streaming constructors: - `HttpApiSchema.StreamUint8Array()` streams raw bytes (default content type: `application/octet-stream`) - `HttpApiSchema.StreamNdjson({ schema })` streams typed values as newline-delimited JSON (default content type: `application/x-ndjson`) - `HttpApiSchema.StreamSse(options)` streams typed Server-Sent Events (default content type: `text/event-stream`) With a streaming success schema, the handler returns a `Stream` directly, and the derived client resolves to a typed `Stream` on the consuming side. The stream declaration is also rendered in the OpenAPI documentation. ### Streaming Raw Bytes `HttpApiSchema.StreamUint8Array` declares a binary streaming response. The handler returns a `Stream` that emits chunks at whatever pace you choose. **Example** (Implementing a Binary Streaming Endpoint) ```ts import { NodeHttpServer, NodeRuntime } from "@effect/platform-node" import { Effect, Layer, Schedule, Stream } from "effect" import { HttpRouter } from "effect/http" import { HttpApi, HttpApiBuilder, HttpApiEndpoint, HttpApiGroup, HttpApiSchema } from "effect/http-api" import { createServer } from "node:http" const Api = HttpApi.make("myApi").add( HttpApiGroup.make("group").add( HttpApiEndpoint.get("getStream", "/stream", { // Declare a streaming success response // (default content type: application/octet-stream) success: HttpApiSchema.StreamUint8Array() }) ) ) // Simulate a stream of data const stream = Stream.make("a", "b", "c").pipe( Stream.schedule(Schedule.spaced("500 millis")), Stream.map((s) => new TextEncoder().encode(s)) ) const GroupLayer = HttpApiBuilder.group( Api, "group", (handlers) => handlers.handle( "getStream", // Return the stream directly from the handler () => Effect.succeed(stream) ) ) const ApiLayer = HttpApiBuilder.layer(Api).pipe( Layer.provide(GroupLayer), HttpRouter.serve, Layer.provide(NodeHttpServer.layer(createServer, { port: 3000 })) ) Layer.launch(ApiLayer).pipe(NodeRuntime.runMain) ``` You can test the streaming response using `curl` or any similar HTTP client that supports streaming: ```sh curl 'http://localhost:3000/stream' --no-buffer ``` The response will stream data (`a`, `b`, `c`) with a 500ms interval between each item. ### Streaming Server-Sent Events `HttpApiSchema.StreamSse` declares a Server-Sent Events response. Pass a `data` schema to stream plain values: each stream element is JSON-encoded into the `data` field of an SSE event on the way out, and the derived client decodes it back to the value. **Example** (Implementing an SSE Endpoint) ```ts import { NodeHttpServer, NodeRuntime } from "@effect/platform-node" import { Effect, Layer, Schedule, Schema, Stream } from "effect" import { HttpRouter } from "effect/http" import { HttpApi, HttpApiBuilder, HttpApiEndpoint, HttpApiGroup, HttpApiSchema } from "effect/http-api" import { createServer } from "node:http" const Message = Schema.Struct({ text: Schema.String }) const Api = HttpApi.make("myApi").add( HttpApiGroup.make("group").add( HttpApiEndpoint.get("getEvents", "/events", { // Each stream element is JSON-encoded into the `data` field of an SSE // event (default content type: text/event-stream) success: HttpApiSchema.StreamSse({ data: Message }) }) ) ) const GroupLayer = HttpApiBuilder.group( Api, "group", (handlers) => handlers.handle("getEvents", () => Effect.succeed( Stream.make({ text: "one" }, { text: "two" }, { text: "three" }).pipe( Stream.schedule(Schedule.spaced("500 millis")) ) )) ) const ApiLayer = HttpApiBuilder.layer(Api).pipe( Layer.provide(GroupLayer), HttpRouter.serve, Layer.provide(NodeHttpServer.layer(createServer, { port: 3000 })) ) Layer.launch(ApiLayer).pipe(NodeRuntime.runMain) // curl 'http://localhost:3000/events' --no-buffer // data: {"text":"one"} // // data: {"text":"two"} // // data: {"text":"three"} ``` To control the full event shape instead, pass an `events` schema whose Encoded side matches the SSE wire format: a required `data` string plus optional `id` and `event` fields. The handler then emits whole events. ### Streaming NDJSON `HttpApiSchema.StreamNdjson({ schema })` declares a response of newline-delimited JSON. Each stream element is encoded with `schema` and written as one line of JSON followed by `\n`, including the last. The wire format is the same as for [NDJSON request payloads](#streaming-ndjson). **Example** (Implementing an NDJSON Endpoint) ```ts import { NodeHttpServer, NodeRuntime } from "@effect/platform-node" import { Effect, Layer, Schedule, Schema, Stream } from "effect" import { HttpRouter } from "effect/http" import { HttpApi, HttpApiBuilder, HttpApiEndpoint, HttpApiGroup, HttpApiSchema } from "effect/http-api" import { createServer } from "node:http" const Message = Schema.Struct({ text: Schema.String }) const Api = HttpApi.make("myApi").add( HttpApiGroup.make("group").add( HttpApiEndpoint.get("getMessages", "/messages", { // Each stream element is written as one line of JSON // (default content type: application/x-ndjson) success: HttpApiSchema.StreamNdjson({ schema: Message }) }) ) ) const GroupLayer = HttpApiBuilder.group( Api, "group", (handlers) => handlers.handle("getMessages", () => Effect.succeed( Stream.make({ text: "one" }, { text: "two" }, { text: "three" }).pipe( Stream.schedule(Schedule.spaced("500 millis")) ) )) ) const ApiLayer = HttpApiBuilder.layer(Api).pipe( Layer.provide(GroupLayer), HttpRouter.serve, Layer.provide(NodeHttpServer.layer(createServer, { port: 3000 })) ) Layer.launch(ApiLayer).pipe(NodeRuntime.runMain) // curl 'http://localhost:3000/messages' --no-buffer // {"text":"one"} // {"text":"two"} // {"text":"three"} ``` `StreamNdjson` has no `error` schema. If the handler's stream fails after the response has started, the connection is aborted, so the client sees a body read error and never a clean end. Typed failures mid-stream need `StreamSse` (see [Typed Stream Failures](#typed-stream-failures)). Some NDJSON APIs report a failure as an ordinary line in their own JSON format, usually the last line of a successful response. Docker's image build, for example, ends with `{"error":"...","errorDetail":{...}}` when a step fails. Declare such a body as a union of the line shapes, so the error line is an element, and decide on the client where it ends the stream. **Example** (Handling an Error Line in an NDJSON Response) ```ts import { Effect, Schema, Stream } from "effect" import { HttpApi, HttpApiBuilder, HttpApiClient, HttpApiEndpoint, HttpApiGroup, HttpApiSchema } from "effect/http-api" const BuildMessage = Schema.Struct({ stream: Schema.String }) const BuildErrorLine = Schema.Struct({ error: Schema.String, errorDetail: Schema.optional(Schema.Struct({ code: Schema.optional(Schema.Number), message: Schema.String })) }) // Members are tried in order, so a line with an `error` field // is an error line even if it also has a `stream` field const BuildLine = Schema.Union([BuildErrorLine, BuildMessage]) class BuildFailed extends Schema.TaggedError()("BuildFailed", { message: Schema.String }) {} const Api = HttpApi.make("docker").add( HttpApiGroup.make("images").add( HttpApiEndpoint.post("build", "/build", { success: HttpApiSchema.StreamNdjson({ schema: BuildLine, contentType: "application/json" }) }) ) ) const runBuild = Stream.make({ stream: "Step 1/2 : FROM alpine" }, { stream: "Step 2/2 : RUN exit 3" }).pipe( Stream.concat(Stream.fail(new BuildFailed({ message: "The command returned a non-zero code: 3" }))) ) // Server: write the failure as the last line, then end the body cleanly const ImagesLayer = HttpApiBuilder.group( Api, "images", (handlers) => handlers.handle("build", () => Effect.succeed( runBuild.pipe( Stream.catchTag("BuildFailed", (error) => Stream.succeed({ error: error.message })) ) )) ) const program = Effect.gen(function*() { const client = yield* HttpApiClient.make(Api, { baseUrl: "http://localhost:3000" }) // Client: stop after the error line, keeping it as the last element const lines = (yield* client.images.build()).pipe( Stream.takeUntil((line) => "error" in line) ) // Client: or fail with BuildFailed at the error line const messages = (yield* client.images.build()).pipe( Stream.mapEffect((line) => "error" in line ? Effect.fail(new BuildFailed({ message: line.error })) : Effect.succeed(line) ) ) // messages: Stream<{ readonly stream: string }, BuildFailed | HttpClientError | SchemaError> }) ``` Things to know: - `Schema.Union` returns the first member that decodes. Put the error shape first when one line can match both, as Docker's format allows. The order is yours to choose. - When `Stream.mapEffect` fails, no later lines are delivered, no further body chunks are read, and the response body is released. Later lines that arrived in the same chunk as the error line may already have been parsed. - On the server the error line is a normal element. A stream failure that the handler doesn't turn into a line still aborts the connection. ### Consuming Streams with the Derived Client For all three constructors, calling the endpoint on the derived client resolves to a typed `Stream`: ```ts const events = yield * client.group.getEvents() // events: Stream<{ readonly text: string }, ...> yield * Stream.runForEach(events, (message) => Console.log(message.text)) ``` The element types and errors are: | Success schema | Client stream | | -------------------------- | ------------------------------------------------------------------------------------------------------ | | `StreamUint8Array()` | `Stream` | | `StreamNdjson({ schema })` | `Stream` | | `StreamSse(options)` | `Stream`, where `E` is the `error` schema | An NDJSON response is decoded with the same rules as an NDJSON request payload. A malformed line or an element that fails to decode is a `SchemaError`. The client also enforces the declared `maxElementBytes` (1 MiB by default), so a server that never sends `\n` can't make it buffer forever. A breach is an `HttpClientError` with a `DecodeError` reason. A server failure mid-stream is the `HttpClientError` from reading the body. If the endpoint also has a [streaming payload](#streaming-requests), the upload can still be running while the response is read, and a late failure of the payload stream fails the response stream with its error too. ### Typed Stream Failures `HttpApiSchema.StreamSse` accepts an `error` schema describing typed stream failures. Since the HTTP status is already sent when the stream fails, the failure cannot travel as a normal error response. Instead, the server encodes the full `Cause` into a reserved `effect/http-api/stream/failure` event, and the derived client decodes that event and fails the stream with the original cause. **Example** (Declaring a Typed Stream Failure) ```ts class StreamError extends Schema.TaggedError()("StreamError", { reason: Schema.String }) {} const Api = HttpApi.make("myApi").add( HttpApiGroup.make("group").add( HttpApiEndpoint.get("getEvents", "/events", { // The handler may return a Stream that fails with StreamError, // and the client's stream fails with StreamError too success: HttpApiSchema.StreamSse({ data: Message, error: StreamError }) }) ) ) ``` Things to know: - Set a custom status or content type with `HttpApiSchema.status(code)` and the `contentType` option, for example `HttpApiSchema.status(206)(HttpApiSchema.StreamUint8Array({ contentType: "application/custom-bytes" }))`. - `StreamUint8Array` and `StreamNdjson` also take a list of content types for a stream that is sent under more than one, like Docker's `application/vnd.docker.raw-stream` and `application/vnd.docker.multiplexed-stream` logs. The server sends the first entry by default. To send another, wrap the stream in `HttpApiSchema.WithHeaders` with a `"content-type": Schema.Literals([...])` header and return it from the handler. OpenAPI lists the stream under every entry, and the derived client decodes any of them. An empty list, or two entries that match after normalization, throws. - Wrap a stream schema with `HttpApiSchema.WithHeaders` to declare typed response headers (see [Setting Response Headers](#setting-response-headers)). The handler returns `HttpApiSchema.withHeaders({ body, headers })` with the stream as `body`, and the client resolves to the same shape. - An endpoint may declare at most one streaming success schema, `HEAD` endpoints cannot declare one, and streaming schemas are not supported in error responses. - The `effect/http-api/stream/failure` event name is reserved: `events` schemas may not declare it, and the client treats such an event as a stream failure only when its `data` decodes to a `Cause`. ### Timing Out Streaming Responses Neither server adapter cuts a quiet response stream by default. Node's socket inactivity timeout (`server.timeout`) is off unless you enable it, and `BunHttpServer` disables Bun's idle timeout unless you pass `idleTimeout`. To limit how long a stream may stay quiet, time out the stream the handler returns: - `Stream.timeout(duration)` ends the response normally when no element arrives within `duration`. - `Stream.timeoutOrElse({ duration, orElse: () => Stream.fail(error) })` fails it instead. As with any failure after the response has started, the connection is aborted, unless a `StreamSse` endpoint declares the error and sends it as a [typed failure](#typed-stream-failures). **Example** (Ending a Quiet Stream) ```ts handlers.handle("ticks", () => // End the response when no tick arrives for 60 seconds Effect.succeed(Stream.timeout(ticks, "60 seconds"))) ``` These timeouts are checked each time the server pulls the next element. If the client stops reading, the server stops pulling and no timeout fires. Idle keep-alive connections between requests have no handler at all. Only a socket-level timer covers these cases: an explicit Bun `idleTimeout`, Node's `server.timeout` and `keepAliveTimeout` (5 seconds by default, between requests only), or a proxy with its own idle timeout. Without `idleTimeout`, Bun closes neither stalled readers nor idle keep-alive connections, so a directly exposed Bun server should set one or sit behind such a proxy. Bun 1.3 still closes connections that never send a complete request when `idleTimeout` is `0`. That is Bun's behavior, not something `BunHttpServer` guarantees across Bun versions. ## Upgrading the Connection `HttpApiSchema.Upgrade({ protocol })` declares an endpoint that switches the connection to another protocol with an HTTP/1.1 upgrade, like Docker's `Upgrade: tcp` for container attach. After `101 Switching Protocols` the connection carries raw bytes in both directions as a `Socket`. The handler receives an `upgrade` function that returns the connection, and returns when it is done with it. The `101` is sent when the handler acquires the socket's reader, so the handler can still fail with a declared error before then. Socket operations fail with `SocketError`, which the handler handles itself, since the response has already switched protocols. **Example** (Implementing an Attach Endpoint) ```ts import { Effect, Schema } from "effect" import { HttpApi, HttpApiBuilder, HttpApiEndpoint, HttpApiGroup, HttpApiSchema } from "effect/http-api" class NotFound extends Schema.TaggedError()("NotFound", {}, { httpApiStatus: 404 }) {} const Api = HttpApi.make("myApi").add( HttpApiGroup.make("containers").add( HttpApiEndpoint.post("attach", "/containers/:id/attach", { params: { id: Schema.String }, success: HttpApiSchema.Upgrade({ protocol: "tcp" }), error: NotFound }) ) ) const GroupLayer = HttpApiBuilder.group( Api, "containers", (handlers) => handlers.handle("attach", ({ params, upgrade }) => Effect.gen(function*() { if (params.id !== "abc") return yield* new NotFound() const socket = yield* upgrade() const reader = yield* socket.reader // sends the 101 const writer = yield* socket.writer yield* writer.write("attached\n") const chunks = yield* reader.pull yield* writer.writeAll(chunks) }).pipe( // the connection is already upgraded, so socket failures end the handler Effect.catchTag("SocketError", () => Effect.void), Effect.scoped )) ) ``` The derived client sends `Connection: Upgrade` and `Upgrade: tcp`, and resolves to the `101` response headers and the connection. Any other response is decoded as one of the endpoint's errors, or as one of its ordinary successes when it declares any (see below). ```ts const { headers, socket } = yield * client.containers.attach({ params: { id: "abc" } }) const reader = yield * socket.reader ``` An upgrade endpoint can declare a buffered payload, which is decoded before the handler runs, and typed `101` headers with the `headers` option. The handler passes the headers to `upgrade`, so they can depend on the request, and the client decodes them. **Example** (Choosing the Stream Format from the Payload) ```ts const start = HttpApiEndpoint.post("start", "/exec/:id/start", { params: { id: Schema.String }, payload: Schema.Struct({ Tty: Schema.Boolean }), success: HttpApiSchema.Upgrade({ protocol: "tcp", headers: { "content-type": Schema.Literals([ "application/vnd.docker.raw-stream", "application/vnd.docker.multiplexed-stream" ]) } }) }) // server handlers.handle("start", ({ payload, upgrade }) => Effect.gen(function*() { const socket = yield* upgrade({ headers: { "content-type": payload.Tty ? "application/vnd.docker.raw-stream" : "application/vnd.docker.multiplexed-stream" } }) // ... })) // client const { headers, socket } = yield * client.exec.start({ params: { id }, payload: { Tty: true } }) headers["content-type"] // "application/vnd.docker.raw-stream" | "application/vnd.docker.multiplexed-stream" ``` A server may decline an upgrade and answer with an ordinary response instead (RFC 9110 §7.8). Declare the ordinary successes alongside the upgrade, at statuses other than `101`. The handler either calls `upgrade` or returns one of the ordinary successes; once it has called `upgrade`, it must return nothing. The client returns either the upgraded connection or the decoded ordinary success, and `HttpApiClient.isUpgraded` tells them apart. **Example** (Starting a Detached Exec) ```ts const start = HttpApiEndpoint.post("start", "/exec/:id/start", { params: { id: Schema.String }, payload: Schema.Struct({ Detach: Schema.Boolean }), success: [HttpApiSchema.Upgrade({ protocol: "tcp" }), HttpApiSchema.Empty(200)] }) // server handlers.handle("start", ({ payload, upgrade }) => Effect.gen(function*() { if (payload.Detach) return // answers with an empty 200 const socket = yield* upgrade() // ... })) // client const result = yield * client.exec.start({ params: { id }, payload: { Detach: false } }) if (HttpApiClient.isUpgraded(result)) { const reader = yield * result.socket.reader } ``` Things to know: - The client needs a backend that can hand over the connection: `NodeHttpClient.layerNodeHttp` (Node, Bun 1.4+, Deno) or `NodeHttpClient.layerUndici` (Node, Deno). Fetch and `XMLHttpRequest` cannot send upgrade requests, so the call fails with a `TransportError` before anything is sent. - Serve upgrade endpoints with `NodeHttpServer`, which also works on Bun 1.4+ and Deno. `Bun.serve` and `Deno.serve` only upgrade to WebSocket, so `BunHttpServer` and `DenoHttpServer` fail these upgrades. - Requests that do not ask for the declared protocol get `426 Upgrade Required`, before the payload is decoded. - An endpoint can declare one upgrade, and it cannot be combined with a streaming payload, a streaming success, or another success at status `101`. Upgrades are not supported in error responses. For WebSocket, use `HttpServerRequest.upgrade` and `Socket.makeWebSocket` instead. - `Connection`, `Upgrade`, `Content-Length` and `Transfer-Encoding` cannot be set on the `101`. Headers that fail to encode end the handler with a defect. - The `101` waits for the request body to end. Node 25 and older do not parse upgrade request bodies, so `NodeHttpServer` reads them with `Content-Length` there and answers chunked ones with `411 Length Required`. - Releasing the writer's scope half-closes the connection, and releasing the reader's scope closes it. # Error Handling ## Adding Custom Error Responses Endpoints can declare the errors they may return. Each error is a schema annotated with an HTTP status code via `HttpApiSchema.status(code)`. The status is set once on the schema and reused wherever that schema appears. When your handler fails with a matching error, the framework serializes it and responds with the declared status. **Example** (Defining Error Responses for an Endpoint) ```ts import { NodeHttpServer, NodeRuntime } from "@effect/platform-node" import { Effect, Layer, Schema } from "effect" import { HttpRouter } from "effect/http" import { HttpApi, HttpApiBuilder, HttpApiEndpoint, HttpApiGroup, HttpApiScalar, HttpApiSchema } from "effect/http-api" import { createServer } from "node:http" const User = Schema.Struct({ id: Schema.Int, name: Schema.String }) const UserNotFound = Schema.Struct({ _tag: Schema.tag("UserNotFound"), message: Schema.String }).pipe(HttpApiSchema.status(404)) const Unauthorized = Schema.Struct({ _tag: Schema.tag("Unauthorized") }).pipe(HttpApiSchema.status(401)) const Api = HttpApi.make("MyApi") .add( HttpApiGroup.make("Users") .add( HttpApiEndpoint.get("getUser", "/user/:id", { params: { id: Schema.Int }, success: User, error: [UserNotFound, Unauthorized /** etc. */] }) ) .add( HttpApiEndpoint.delete("deleteUser", "/user/:id", { params: { id: Schema.Int }, error: [UserNotFound, Unauthorized /** etc. */] }) ) ) const GroupLayer = HttpApiBuilder.group( Api, "Users", (handlers) => handlers.handleAll({ getUser: (ctx) => { const id = ctx.params.id if (id === 1) { return Effect.fail(UserNotFound.make({ message: "User not found" })) } return Effect.succeed({ id, name: `User ${id}` }) }, deleteUser: (ctx) => { const id = ctx.params.id if (id === 1) { return Effect.fail(UserNotFound.make({ message: "User not found" })) } return Effect.succeed(void 0) } }) ) const ApiLayer = HttpApiBuilder.layer(Api).pipe( Layer.provide(GroupLayer), Layer.provide(HttpApiScalar.layer(Api)), HttpRouter.serve, Layer.provide(NodeHttpServer.layer(createServer, { port: 3000 })) ) Layer.launch(ApiLayer).pipe(NodeRuntime.runMain) ``` You can test these endpoints. For example: ```sh curl http://localhost:3000/user/1 # Returns 404 Not Found curl http://localhost:3000/user/2 # Returns 200 OK curl -X DELETE http://localhost:3000/user/1 # Returns 404 Not Found curl -X DELETE http://localhost:3000/user/2 # Returns 200 OK ``` ## Predefined Error Types The `HttpApiError` module provides ready-made error schemas for common HTTP status codes (404, 401, etc.). Using these saves you from defining boilerplate error types and keeps error handling consistent across your API. **Example** (Adding a Predefined Error to an Endpoint) ```ts import { NodeHttpServer, NodeRuntime } from "@effect/platform-node" import { Effect, Layer, Schema } from "effect" import { HttpRouter } from "effect/http" import { HttpApi, HttpApiBuilder, HttpApiEndpoint, HttpApiError, HttpApiGroup, HttpApiScalar } from "effect/http-api" import { createServer } from "node:http" const User = Schema.Struct({ id: Schema.Int, name: Schema.String }) const Api = HttpApi.make("MyApi") .add( HttpApiGroup.make("Users") .add( HttpApiEndpoint.get("getUser", "/user/:id", { params: { id: Schema.Int }, success: User, error: [ // Add a 404 error JSON response for this endpoint HttpApiError.NotFound, // Add a 401 error JSON response for unauthorized access HttpApiError.Unauthorized ] }) ) ) const GroupLayer = HttpApiBuilder.group( Api, "Users", (handlers) => handlers .handle("getUser", (ctx) => { const id = ctx.params.id if (id === 1) { return Effect.fail(new HttpApiError.NotFound({})) } return Effect.succeed({ id, name: `User ${id}` }) }) ) const ApiLayer = HttpApiBuilder.layer(Api).pipe( Layer.provide(GroupLayer), Layer.provide(HttpApiScalar.layer(Api)), HttpRouter.serve, Layer.provide(NodeHttpServer.layer(createServer, { port: 3000 })) ) Layer.launch(ApiLayer).pipe(NodeRuntime.runMain) ``` | Name | Status | Description | | --------------------- | ------ | -------------------------------------------------------------------------------------------------- | | `HttpApiDecodeError` | 400 | Represents an error where the request did not match the expected schema. Includes detailed issues. | | `BadRequest` | 400 | Indicates that the request was malformed or invalid. | | `Unauthorized` | 401 | Indicates that authentication is required but missing or invalid. | | `Forbidden` | 403 | Indicates that the client does not have permission to access the requested resource. | | `NotFound` | 404 | Indicates that the requested resource could not be found. | | `MethodNotAllowed` | 405 | Indicates that the HTTP method used is not allowed for the requested resource. | | `NotAcceptable` | 406 | Indicates that the requested resource cannot be delivered in a format acceptable to the client. | | `RequestTimeout` | 408 | Indicates that the server timed out waiting for the client request. | | `Conflict` | 409 | Indicates a conflict in the request, such as conflicting data. | | `Gone` | 410 | Indicates that the requested resource is no longer available and will not return. | | `InternalServerError` | 500 | Indicates an unexpected server error occurred. | | `NotImplemented` | 501 | Indicates that the requested functionality is not implemented on the server. | | `ServiceUnavailable` | 503 | Indicates that the server is temporarily unavailable, often due to maintenance or overload. | #### Predefined NoContent Error Types Each predefined error also has a `NoContent` variant that responds with the status code but no body. **Example** (Using a Predefined NoContent Error Type) ```ts import { NodeHttpServer, NodeRuntime } from "@effect/platform-node" import { Effect, Layer, Schema } from "effect" import { HttpRouter } from "effect/http" import { HttpApi, HttpApiBuilder, HttpApiEndpoint, HttpApiError, HttpApiGroup, HttpApiScalar } from "effect/http-api" import { createServer } from "node:http" const User = Schema.Struct({ id: Schema.Int, name: Schema.String }) const Api = HttpApi.make("MyApi") .add( HttpApiGroup.make("Users") .add( HttpApiEndpoint.get("getUser", "/user/:id", { params: { id: Schema.Int }, success: User, error: [ // Add a 404 error no-content response for this endpoint HttpApiError.NotFoundNoContent, // Add a 401 error no-content response for unauthorized access HttpApiError.UnauthorizedNoContent ] }) ) ) const GroupLayer = HttpApiBuilder.group( Api, "Users", (handlers) => handlers .handle("getUser", (ctx) => { const id = ctx.params.id if (id === 1) { return Effect.fail(new HttpApiError.NotFound({})) } return Effect.succeed({ id, name: `User ${id}` }) }) ) const ApiLayer = HttpApiBuilder.layer(Api).pipe( Layer.provide(GroupLayer), Layer.provide(HttpApiScalar.layer(Api)), HttpRouter.serve, Layer.provide(NodeHttpServer.layer(createServer, { port: 3000 })) ) Layer.launch(ApiLayer).pipe(NodeRuntime.runMain) ``` ## Customizing Schema Error Responses By default, when a request fails schema validation (e.g., an invalid query parameter or a malformed path parameter), the framework responds with an empty `400 Bad Request`. If you want to replace that response with a custom error, use `HttpApiMiddleware.layerSchemaErrorTransform`. This function creates a [middleware](#middlewares) layer that intercepts any `SchemaError` thrown during request decoding and lets you return your own error instead. **Example** (Returning a Custom Error on Validation Failure) In this example, if a client sends a non-integer `id` query parameter, the API responds with a `422` status and a JSON body describing the problem, instead of the default empty `400`. ```ts import { NodeHttpServer, NodeRuntime } from "@effect/platform-node" import { Effect, Layer, Schema } from "effect" import { HttpRouter } from "effect/http" import { HttpApi, HttpApiBuilder, HttpApiEndpoint, HttpApiGroup, HttpApiMiddleware, HttpApiScalar, HttpApiSchema } from "effect/http-api" import { createServer } from "node:http" // Define a custom error for validation failures class ValidationError extends Schema.TaggedError()( "ValidationError", { message: Schema.String } ) {} // Define the middleware service, declaring the error it can produce class SchemaErrorHandler extends HttpApiMiddleware.Service()( "api/SchemaErrorHandler", { error: ValidationError.pipe(HttpApiSchema.status(422)) } ) {} // Implement the middleware layer const SchemaErrorHandlerLayer = HttpApiMiddleware.layerSchemaErrorTransform( SchemaErrorHandler, (schemaError) => Effect.fail( new ValidationError({ message: `Invalid request: ${schemaError.message}` }) ) ) const User = Schema.Struct({ id: Schema.Int, name: Schema.String }) const Api = HttpApi.make("MyApi").add( HttpApiGroup.make("Users").add( HttpApiEndpoint.get("getUser", "/user", { query: { id: Schema.Int }, success: User }) // Attach the middleware to this endpoint only .middleware(SchemaErrorHandler) ) ) const GroupLayer = HttpApiBuilder.group( Api, "Users", (handlers) => handlers.handle("getUser", (ctx) => Effect.succeed({ id: ctx.query.id, name: `User ${ctx.query.id}` })) ) const ApiLayer = HttpApiBuilder.layer(Api).pipe( Layer.provide(GroupLayer), Layer.provide(SchemaErrorHandlerLayer), Layer.provide(HttpApiScalar.layer(Api)), HttpRouter.serve, Layer.provide(NodeHttpServer.layer(createServer, { port: 3000 })) ) Layer.launch(ApiLayer).pipe(NodeRuntime.runMain) // Test: // curl "http://localhost:3000/user?id=1" # 200 OK // curl "http://localhost:3000/user?id=abc" # 422 with ValidationError JSON ``` The middleware can be attached at different scopes: - **Endpoint**: `.middleware(SchemaErrorHandler)` on a single endpoint (as shown above). - **Group**: `.middleware(SchemaErrorHandler)` on a group to cover all its endpoints. - **API**: `.middleware(SchemaErrorHandler)` on the API to cover every endpoint. # Middlewares Middleware lets you run shared logic — like logging or authentication — before (or around) your handlers. Define a middleware as a class extending `HttpApiMiddleware.Service`, implement it as a `Layer`, and attach it to an endpoint, a group, or the entire API. **Example** (Defining a Logger Middleware) ```ts import { NodeHttpServer, NodeRuntime } from "@effect/platform-node" import { Effect, Layer, Schema } from "effect" import { HttpRouter, HttpServerRequest } from "effect/http" import { HttpApi, HttpApiBuilder, HttpApiEndpoint, HttpApiGroup, HttpApiMiddleware, HttpApiScalar, HttpApiSchema } from "effect/http-api" import { createServer } from "node:http" class Logger extends HttpApiMiddleware.Service()("Http/Logger", { // default is 500 Internal Server Error with JSON encoding error: Schema.String .pipe( HttpApiSchema.status(405), // override default status code HttpApiSchema.asText() // override default encoding ) }) {} const User = Schema.Struct({ id: Schema.Finite, name: Schema.String }) const Api = HttpApi.make("api").add( HttpApiGroup.make("group").add( HttpApiEndpoint.get("getUser", "/user/:id", { params: { id: Schema.Int }, success: User }) // Apply the middleware to a single endpoint .middleware(Logger) ) // Or apply the middleware to the entire group .middleware(Logger) ) const GroupLayer = HttpApiBuilder.group( Api, "group", (handlers) => handlers.handle("getUser", (ctx) => { const id = ctx.params.id return Effect.succeed({ id, name: `User ${id}` }) }) ) const LoggerLayer = Layer.effect( Logger, Effect.gen(function*() { yield* Effect.log("creating Logger middleware") return (res) => Effect.gen(function*() { const request = yield* HttpServerRequest.HttpServerRequest yield* Effect.log(`Request: ${request.method} ${request.url}`) return yield* res }) }) ) const ApiLayer = HttpApiBuilder.layer(Api).pipe( Layer.provide(GroupLayer), Layer.provide(HttpApiScalar.layer(Api)), Layer.provide(LoggerLayer), HttpRouter.serve, Layer.provide(NodeHttpServer.layer(createServer, { port: 3000 })) ) Layer.launch(ApiLayer).pipe(NodeRuntime.runMain) // Test this with this curl command: // curl "http://localhost:3000/user/1" ``` ## Interdependent Middleware Middleware can depend on services provided by other middleware. Declare the dependency with `requires` and declare the produced service with `provides`. When you attach interdependent middleware to an endpoint, group, or API, the middleware that uses `requires` must come **BEFORE** the middleware that provides that service. The earlier middleware wraps the later middleware, so it can consume the service that the later middleware adds to the request effect. **Example** (Middleware that consumes another middleware's output) ```ts import { Context, Effect, Layer, Schema } from "effect" import { HttpApi, HttpApiEndpoint, HttpApiGroup, HttpApiMiddleware } from "effect/http-api" class AuthInfo extends Context.Service()("AuthInfo") {} class LoadAuth extends HttpApiMiddleware.Service()("LoadAuth") {} class RequireAuth extends HttpApiMiddleware.Service()("RequireAuth") {} const Api = HttpApi.make("api").add( HttpApiGroup.make("users").add( HttpApiEndpoint.get("me", "/me", { success: Schema.String }) // RequireAuth reads AuthInfo, so it must appear first. .middleware(RequireAuth) // LoadAuth provides AuthInfo to middleware that appears before it. .middleware(LoadAuth) ) ) const LoadAuthLayer = Layer.effect( LoadAuth, Effect.succeed((effect) => Effect.provideService(effect, AuthInfo, { userId: "user-1" }) ) ) const RequireAuthLayer = Layer.effect( RequireAuth, Effect.succeed( Effect.fnUntraced(function*(effect) { const authInfo = yield* AuthInfo yield* Effect.log(`authenticated user ${authInfo.userId}`) return yield* effect }) ) ) ``` # Security The `HttpApiSecurity` module lets you declare how an endpoint is protected. These declarations show up in the generated OpenAPI spec and are enforced at runtime through middleware. Supported authorization types: | Authorization Type | Description | | ------------------------ | ---------------------------------------------------------------- | | `HttpApiSecurity.apiKey` | API key authorization via headers, query parameters, or cookies. | | `HttpApiSecurity.basic` | HTTP Basic authentication. | | `HttpApiSecurity.bearer` | Bearer token authentication. | Attach a security scheme to an endpoint, group, or the entire API via `HttpApiMiddleware`. **Example** (Defining Security Middleware) ```ts import { Context, Schema } from "effect" import { HttpApi, HttpApiEndpoint, HttpApiGroup, HttpApiMiddleware, HttpApiSecurity } from "effect/http-api" // Define a schema for the "User" class User extends Schema.Class("User")({ id: Schema.Finite }) {} // Define a schema for the "Unauthorized" error class Unauthorized extends Schema.TaggedError()( "Unauthorized", {}, // Specify the HTTP status code for unauthorized errors { httpApiStatus: 401 } ) {} // Define a Context.Tag for the authenticated user class CurrentUser extends Context.Service()("CurrentUser") {} // Create the Authorization middleware class Authorization extends HttpApiMiddleware.Service()( "Authorization", { // Define the error schema for unauthorized access error: Unauthorized, // Add security definitions security: { // ┌─── Custom name for the security definition // ▼ myBearer: HttpApiSecurity.bearer // Additional security definitions can be added here. // They will attempt to be resolved in the order they are defined. } } ) {} const api = HttpApi.make("api") .add( HttpApiGroup.make("group") .add( HttpApiEndpoint.get("get", "/", { success: Schema.String }) // Apply the middleware to a single endpoint .middleware(Authorization) ) // Or apply the middleware to the entire group .middleware(Authorization) ) // Or apply the middleware to the entire API .middleware(Authorization) ``` ## Implementing HttpApiSecurity middleware To enforce a security scheme, implement its middleware as a `Layer`. The layer returns an object with a handler for each security definition. Each handler receives the credential (e.g., a Bearer token as a `Redacted` value) and must return the resource the middleware provides (e.g., the current user). **Example** (Implementing Bearer Token Authentication Middleware) ```ts import { Context, Effect, Layer, Redacted, Schema } from "effect" import { HttpApiMiddleware, HttpApiSecurity } from "effect/http-api" class User extends Schema.Class("User")({ id: Schema.Finite }) {} class Unauthorized extends Schema.TaggedError()( "Unauthorized", {}, // Specify the HTTP status code for unauthorized errors { httpApiStatus: 401 } ) {} class CurrentUser extends Context.Service()("CurrentUser") {} class Authorization extends HttpApiMiddleware.Service()( "Authorization", { error: Unauthorized, security: { myBearer: HttpApiSecurity.bearer } } ) {} const AuthorizationLayer = Layer.succeed( Authorization, // Return the security handlers for the middleware { // Define the handler for the Bearer token // The Bearer token is redacted for security myBearer: (effect, opts) => Effect.provideServiceEffect( effect, CurrentUser, Effect.gen(function*() { yield* Effect.log( "checking bearer token", Redacted.value(opts.credential) ) // Return a mock User object as the CurrentUser return new User({ id: 1 }) }) ) } ) ``` ## Adding Descriptions to Security Definitions Use `HttpApiSecurity.annotate` to attach metadata — like a description — to a security definition. This metadata appears in the generated docs. **Example** (Adding a Description to a Bearer Token Security Definition) ```ts import { Context, Schema } from "effect" import { HttpApiMiddleware, HttpApiSecurity, OpenApi } from "effect/http-api" class User extends Schema.Class("User")({ id: Schema.Finite }) {} class Unauthorized extends Schema.TaggedError()( "Unauthorized", {}, // Specify the HTTP status code for unauthorized errors { httpApiStatus: 401 } ) {} class CurrentUser extends Context.Service()("CurrentUser") {} class Authorization extends HttpApiMiddleware.Service()( "Authorization", { error: Unauthorized, security: { myBearer: HttpApiSecurity.bearer.pipe( // Add a description to the security definition HttpApiSecurity.annotate(OpenApi.Description, "my description") ) } } ) {} ``` ## Setting HttpApiSecurity cookies Use `HttpApiBuilder.securitySetCookie` to set a security cookie from a handler. The cookie is created with `HttpOnly` and `Secure` flags by default. **Example** (Setting a Security Cookie in a Login Handler) ```ts import { Redacted, Schema } from "effect" import { HttpApi, HttpApiBuilder, HttpApiEndpoint, HttpApiGroup, HttpApiSecurity } from "effect/http-api" const Api = HttpApi.make("MyApi") .add( HttpApiGroup.make("Users") .add( HttpApiEndpoint.get("login", "/login", { params: { success: Schema.String } }) ) ) // Define the security configuration for an API key stored in a cookie const security = HttpApiSecurity.apiKey({ // Specify that the API key is stored in a cookie in: "cookie", // Define the cookie name, key: "token" }) const UsersApiLayer = HttpApiBuilder.group(Api, "Users", (handlers) => handlers.handle("login", () => // Set the security cookie with a redacted value HttpApiBuilder.securitySetCookie(security, Redacted.make("keep me secret")))) ``` # Using Services Inside a HttpApiEndpoint Handlers can access any Effect service. Because `HttpApiBuilder.group` returns an `Effect`, you can `yield*` services directly inside your handler logic. **Example** (Using Services in a Endpoint Implementation) ```ts import { NodeHttpServer, NodeRuntime } from "@effect/platform-node" import { Context, Effect, Layer, Schema } from "effect" import { HttpRouter } from "effect/http" import { HttpApi, HttpApiBuilder, HttpApiEndpoint, HttpApiGroup, HttpApiScalar } from "effect/http-api" import { createServer } from "node:http" const User = Schema.Struct({ id: Schema.Int, name: Schema.String }) // Define the UsersRepository service class UsersRepository extends Context.Service Effect.Effect }>()("UsersRepository") {} const Api = HttpApi.make("MyApi") .add( HttpApiGroup.make("Users") .add( HttpApiEndpoint.get("getUser", "/user/:id", { params: { id: Schema.Int }, success: User }) ) ) const GroupLayer = HttpApiBuilder.group( Api, "Users", (handlers) => handlers .handle("getUser", (ctx) => { const id = ctx.params.id return Effect.gen(function*() { // Access the UsersRepository service const repository = yield* UsersRepository return yield* repository.findById(id) }) }) ) const ApiLayer = HttpApiBuilder.layer(Api).pipe( Layer.provide(GroupLayer), Layer.provide(HttpApiScalar.layer(Api)), Layer.provide( Layer.succeed(UsersRepository, { findById: (id) => Effect.succeed({ id, name: `User ${id}` }) }) ), HttpRouter.serve, Layer.provide(NodeHttpServer.layer(createServer, { port: 3000 })) ) Layer.launch(ApiLayer).pipe(NodeRuntime.runMain) ``` # OpenAPI Documentation Add interactive API documentation with `HttpApiScalar` (Scalar UI) or `HttpApiSwagger` (Swagger UI). Both read your API definition and generate a browsable docs page at `/docs`. **Example** (Adding Scalar Documentation to an API) ```ts import { NodeHttpServer, NodeRuntime } from "@effect/platform-node" import { Effect, Layer, Schema } from "effect" import { HttpRouter } from "effect/http" import { HttpApi, HttpApiBuilder, HttpApiEndpoint, HttpApiGroup, HttpApiScalar } from "effect/http-api" import { createServer } from "node:http" const User = Schema.Struct({ id: Schema.Int, name: Schema.String }) const IdParam = Schema.Int const Api = HttpApi.make("MyApi") .add( HttpApiGroup.make("Users") .add( HttpApiEndpoint.get("getUsers", "/users", { success: Schema.Array(User) }), HttpApiEndpoint.get("getUser", "/user/:id", { params: { id: IdParam }, success: User }), HttpApiEndpoint.post("createUser", "/user", { payload: User, success: User }), HttpApiEndpoint.delete("deleteUser", "/user/:id", { params: { id: IdParam } }), HttpApiEndpoint.patch("updateUser", "/user/:id", { params: { id: IdParam }, // Specify the schema for the request payload payload: Schema.Struct({ name: Schema.String // Only the name can be updated }), // Specify the schema for a successful response success: User }) ) ) const GroupLayer = HttpApiBuilder.group( Api, "Users", (handlers) => handlers.handleAll({ getUsers: () => Effect.succeed( [{ id: 1, name: "User 1" }, { id: 2, name: "User 2" }] ), getUser: (ctx) => { const id = ctx.params.id return Effect.succeed({ id, name: `User ${id}` }) }, createUser: (ctx) => { const user = ctx.payload return Effect.succeed(user) }, deleteUser: (ctx) => { const id = ctx.params.id return Effect.log(`Deleting user ${id}`) }, updateUser: (ctx) => { const id = ctx.params.id return Effect.succeed({ id, name: `User ${id}` }) } }) ) const ApiLayer = HttpApiBuilder.layer(Api).pipe( Layer.provide(GroupLayer), Layer.provide(HttpApiScalar.layer(Api)), // "/docs" is the default path. HttpRouter.serve, Layer.provide(NodeHttpServer.layer(createServer, { port: 3000 })) ) Layer.launch(ApiLayer).pipe(NodeRuntime.runMain) ``` After running the server, open your browser and navigate to http://localhost:3000/docs. This URL will display the Scalar documentation, allowing you to explore the API's endpoints, request parameters, and response structures interactively. ## Adding OpenAPI Annotations Annotations let you enrich the generated OpenAPI spec with titles, descriptions, server URLs, and more. They are added via the `.annotate` method on `HttpApi`, `HttpApiGroup`, or `HttpApiEndpoint`. #### HttpApi Below is a list of available annotations for a top-level `HttpApi`. They can be added using the `.annotate` method: | Annotation | Description | | --------------------------- | ------------------------------------------------------------------------------------------------------------------ | | `HttpApi.AdditionalSchemas` | Adds custom schemas to the final OpenAPI specification. Only schemas with an `identifier` annotation are included. | | `OpenApi.Description` | Sets a general description for the API. | | `OpenApi.Title` | Sets the title of the API. | | `OpenApi.Version` | Sets the version of the API. | | `OpenApi.License` | Defines the license used by the API. | | `OpenApi.Summary` | Provides a brief summary of the API. | | `OpenApi.Servers` | Lists server URLs and optional metadata such as variables. | | `OpenApi.Override` | Merges the supplied fields into the resulting specification. | | `OpenApi.Transform` | Allows you to modify the final specification with a custom function. | **Example** (Annotating the Top-Level API) ```ts import { Schema } from "effect" import { HttpApi, OpenApi } from "effect/http-api" const api = HttpApi.make("api") // Provide additional schemas .annotate(HttpApi.AdditionalSchemas, [ Schema.String.annotate({ identifier: "MyString" }) ]) // Add a description .annotate(OpenApi.Description, "my description") // Set license information .annotate(OpenApi.License, { name: "MIT", url: "http://example.com" }) // Provide a summary .annotate(OpenApi.Summary, "my summary") // Define servers .annotate(OpenApi.Servers, [ { url: "http://example.com", description: "example", variables: { a: { default: "b", enum: ["c"], description: "d" } } } ]) // Override parts of the generated specification .annotate(OpenApi.Override, { tags: [{ name: "a", description: "a-description" }] }) // Apply a transform function to the final specification .annotate(OpenApi.Transform, (spec) => ({ ...spec, tags: [...spec.tags, { name: "b", description: "b-description" }] })) // Generate the OpenAPI specification from the annotated API const spec = OpenApi.fromApi(api) console.log(JSON.stringify(spec, null, 2)) /* Output: { "openapi": "3.1.0", "info": { "title": "Api", "version": "0.0.1", "description": "my description", "license": { "name": "MIT", "url": "http://example.com" }, "summary": "my summary" }, "paths": {}, "components": { "schemas": { "MyString": { "type": "string" } }, "securitySchemes": {} }, "security": [], "tags": [ { "name": "a", "description": "a-description" }, { "name": "b", "description": "b-description" } ], "servers": [ { "url": "http://example.com", "description": "example", "variables": { "a": { "default": "b", "enum": [ "c" ], "description": "d" } } } ] } */ ``` #### HttpApiGroup The following annotations can be added to an `HttpApiGroup`: | Annotation | Description | | ---------------------- | --------------------------------------------------------------------- | | `OpenApi.Description` | Sets a description for this group. | | `OpenApi.ExternalDocs` | Provides external documentation links for the group. | | `OpenApi.Override` | Merges specified fields into the resulting specification. | | `OpenApi.Transform` | Lets you modify the final group specification with a custom function. | | `OpenApi.Exclude` | Excludes the group from the final OpenAPI specification. | **Example** (Annotating a Group) ```ts import { HttpApi, HttpApiGroup, OpenApi } from "effect/http-api" const api = HttpApi.make("api") .add( HttpApiGroup.make("group") // Add a description for the group .annotate(OpenApi.Description, "my description") // Provide external documentation links .annotate(OpenApi.ExternalDocs, { url: "http://example.com", description: "example" }) // Override parts of the final output .annotate(OpenApi.Override, { name: "my name" }) // Transform the final specification for this group .annotate(OpenApi.Transform, (spec) => ({ ...spec, name: spec.name + "-transformed" })) ) .add( HttpApiGroup.make("excluded") // Exclude the group from the final specification .annotate(OpenApi.Exclude, true) ) // Generate the OpenAPI spec const spec = OpenApi.fromApi(api) console.log(JSON.stringify(spec, null, 2)) /* Output: { "openapi": "3.1.0", "info": { "title": "Api", "version": "0.0.1" }, "paths": {}, "components": { "schemas": {}, "securitySchemes": {} }, "security": [], "tags": [ { "name": "my name-transformed", "description": "my description", "externalDocs": { "url": "http://example.com", "description": "example" } } ] } */ ``` #### HttpApiEndpoint For an `HttpApiEndpoint`, you can use the following annotations: | Annotation | Description | | ---------------------- | --------------------------------------------------------------------------- | | `OpenApi.Description` | Adds a description for this endpoint. | | `OpenApi.Summary` | Provides a short summary of the endpoint's purpose. | | `OpenApi.Deprecated` | Marks the endpoint as deprecated. | | `OpenApi.ExternalDocs` | Supplies external documentation links for the endpoint. | | `OpenApi.Override` | Merges specified fields into the resulting specification for this endpoint. | | `OpenApi.Transform` | Lets you modify the final endpoint specification with a custom function. | | `OpenApi.Exclude` | Excludes the endpoint from the final OpenAPI specification. | **Example** (Annotating an Endpoint) ```ts import { Schema } from "effect" import { HttpApi, HttpApiEndpoint, HttpApiGroup, OpenApi } from "effect/http-api" const api = HttpApi.make("api").add( HttpApiGroup.make("group") .add( HttpApiEndpoint.get("get", "/", { success: Schema.String }) // Add a description .annotate(OpenApi.Description, "my description") // Provide a summary .annotate(OpenApi.Summary, "my summary") // Mark the endpoint as deprecated .annotate(OpenApi.Deprecated, true) // Provide external documentation .annotate(OpenApi.ExternalDocs, { url: "http://example.com", description: "example" }) ) .add( HttpApiEndpoint.get("excluded", "/excluded", { success: Schema.String }) // Exclude this endpoint from the final specification .annotate(OpenApi.Exclude, true) ) ) // Generate the OpenAPI spec const spec = OpenApi.fromApi(api) console.log(JSON.stringify(spec, null, 2)) /* Output: { "openapi": "3.1.0", "info": { "title": "Api", "version": "0.0.1" }, "paths": { "/": { "get": { "tags": [ "group" ], "operationId": "group.get", "parameters": [], "security": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/String_" } } } }, "400": { "description": "The request or response did not match the expected schema", "content": { "application/json": { "schema": { "type": "object", "properties": { "_tag": { "type": "string", "enum": [ "HttpApiSchemaError" ] }, "message": { "$ref": "#/components/schemas/String_" } }, "required": [ "_tag", "message" ], "additionalProperties": false } } } } }, "description": "my description", "summary": "my summary", "deprecated": true, "externalDocs": { "url": "http://example.com", "description": "example" } } } }, "components": { "schemas": { "String_": { "type": "string" } }, "securitySchemes": {} }, "security": [], "tags": [ { "name": "group" } ] } */ ``` The default response description is "Success". You can override this by annotating the schema. **Example** (Defining a custom response description) ```ts import { Schema } from "effect" import { HttpApi, HttpApiEndpoint, HttpApiGroup, OpenApi } from "effect/http-api" const User = Schema.Struct({ id: Schema.Finite, name: Schema.String }).annotate({ identifier: "User" }) const api = HttpApi.make("api").add( HttpApiGroup.make("group").add( HttpApiEndpoint.get("getUsers", "/users", { success: Schema.Array(User).annotate({ description: "Returns an array of users" }) }) ) ) const spec = OpenApi.fromApi(api) console.log(JSON.stringify(spec.paths, null, 2)) /* Output: { "/users": { "get": { "tags": [ "group" ], "operationId": "group.getUsers", "parameters": [], "security": [], "responses": { "200": { "description": "Returns an array of users", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number" }, "name": { "$ref": "#/components/schemas/String_" } }, "required": [ "id", "name" ], "additionalProperties": false }, "description": "Returns an array of users" } } } }, "400": { "description": "The request or response did not match the expected schema", "content": { "application/json": { "schema": { "type": "object", "properties": { "_tag": { "type": "string", "enum": [ "HttpApiSchemaError" ] }, "message": { "$ref": "#/components/schemas/String_" } }, "required": [ "_tag", "message" ], "additionalProperties": false } } } } } } } } */ ``` ## Top Level Groups When a group is `topLevel`, its name is not prepended to operation IDs in the OpenAPI spec. Use this when the group is just for tagging and you want shorter, cleaner operation IDs. **Example** (Using a Top-Level Group) ```ts import { Schema } from "effect" import { HttpApi, HttpApiEndpoint, HttpApiGroup, OpenApi } from "effect/http-api" const api = HttpApi.make("api").add( // Mark the group as top-level HttpApiGroup.make("group", { topLevel: true }).add( HttpApiEndpoint.get("get", "/", { success: Schema.String }) ) ) // Generate the OpenAPI spec const spec = OpenApi.fromApi(api) console.log(JSON.stringify(spec.paths, null, 2)) /* Output: { "/": { "get": { // The operation ID is not prefixed with "group" "tags": [ "group" ], "operationId": "get", "parameters": [], "security": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/String_" } } } }, "400": { "description": "The request or response did not match the expected schema", "content": { "application/json": { "schema": { "type": "object", "properties": { "_tag": { "type": "string", "enum": [ "HttpApiSchemaError" ] }, "message": { "$ref": "#/components/schemas/String_" } }, "required": [ "_tag", "message" ], "additionalProperties": false } } } } } } } } */ ``` # Deriving a Client The `HttpApiClient` module generates a fully typed client from your API definition. Each endpoint becomes a method — grouped by `HttpApiGroup` name — so calling your API is as simple as calling a function. **Example** (Deriving and Using a Client) ```ts import { NodeHttpServer, NodeRuntime } from "@effect/platform-node" import { Effect, Layer, Schema } from "effect" import { HttpRouter } from "effect/http" import { FetchHttpClient } from "effect/http" import { HttpApi, HttpApiBuilder, HttpApiClient, HttpApiEndpoint, HttpApiGroup } from "effect/http-api" import { createServer } from "node:http" const Api = HttpApi.make("MyApi") .add( HttpApiGroup.make("Greetings") .add( HttpApiEndpoint.get("hello", "/", { success: Schema.String }) ) ) const GroupLayer = HttpApiBuilder.group( Api, "Greetings", (handlers) => handlers.handle("hello", () => Effect.succeed("Hello, World!")) ) const ApiLayer = HttpApiBuilder.layer(Api).pipe( Layer.provide(GroupLayer), HttpRouter.serve, Layer.provide(NodeHttpServer.layer(createServer, { port: 3000 })) ) Layer.launch(ApiLayer).pipe(NodeRuntime.runMain) // Create a program that derives and uses the client const program = Effect.gen(function*() { // Derive the client const client = yield* HttpApiClient.make(Api, { baseUrl: "http://localhost:3000" }) // Call the "hello-world" endpoint const hello = yield* client.Greetings.hello() console.log(hello) }) // Provide a Fetch-based HTTP client and run the program Effect.runFork(program.pipe(Effect.provide(FetchHttpClient.layer))) /* Output: [18:55:26.051] INFO (#2): Listening on http://0.0.0.0:3000 [18:55:26.057] INFO (#12) http.span=2ms: Sent HTTP response { 'http.method': 'GET', 'http.url': '/', 'http.status': 200 } Hello, World! */ ``` ## Top Level Groups When a group is `topLevel`, its endpoints are exposed as top-level methods on the client instead of being nested under the group name. **Example** (Using a Top-Level Group in the Client) ```ts import { NodeHttpServer, NodeRuntime } from "@effect/platform-node" import { Effect, Layer, Schema } from "effect" import { HttpRouter } from "effect/http" import { FetchHttpClient } from "effect/http" import { HttpApi, HttpApiBuilder, HttpApiClient, HttpApiEndpoint, HttpApiGroup } from "effect/http-api" import { createServer } from "node:http" const Api = HttpApi.make("MyApi") .add( HttpApiGroup.make("Greetings", { topLevel: true }) .add( HttpApiEndpoint.get("hello", "/", { success: Schema.String }) ) ) const GroupLayer = HttpApiBuilder.group( Api, "Greetings", (handlers) => handlers.handle("hello", () => Effect.succeed("Hello, World!")) ) const ApiLayer = HttpApiBuilder.layer(Api).pipe( Layer.provide(GroupLayer), HttpRouter.serve, Layer.provide(NodeHttpServer.layer(createServer, { port: 3000 })) ) Layer.launch(ApiLayer).pipe(NodeRuntime.runMain) const program = Effect.gen(function*() { const client = yield* HttpApiClient.make(Api, { baseUrl: "http://localhost:3000" }) // The `hello` method is not nested under the "group" name const hello = yield* client.hello() console.log(hello) }) Effect.runFork(program.pipe(Effect.provide(FetchHttpClient.layer))) ``` # Converting to a Web Handler If you need to plug your API into an existing HTTP server (instead of using `NodeHttpServer`), convert it to a standard web handler with `HttpApiBuilder.toWebHandler`. The returned `handler` function takes a `Request` and returns a `Response`. **Example** (Creating and Serving a Web Handler) ```ts import { Effect, Layer, Schema } from "effect" import { HttpRouter, HttpServer } from "effect/http" import { HttpApi, HttpApiBuilder, HttpApiEndpoint, HttpApiGroup, HttpApiScalar } from "effect/http-api" import * as http from "node:http" const Api = HttpApi.make("myApi").add( HttpApiGroup.make("group").add( HttpApiEndpoint.get("get", "/", { success: Schema.String }) ) ) const GroupLayer = HttpApiBuilder.group( Api, "group", (handlers) => handlers.handle("get", () => Effect.succeed("Hello, world!")) ) const ApiLayer = HttpApiBuilder.layer(Api).pipe( Layer.provide(GroupLayer), Layer.provide(HttpApiScalar.layer(Api)), Layer.provide(HttpServer.layerServices) ) // Convert the API to a web handler const { dispose, handler } = HttpRouter.toWebHandler( Layer.mergeAll(ApiLayer) ) // Serving the handler using a custom HTTP server http .createServer(async (req, res) => { const url = `http://${req.headers.host}${req.url}` const init: RequestInit = { method: req.method! } const response = await handler(new Request(url, init)) res.writeHead( response.status, response.statusText, Object.fromEntries(response.headers.entries()) ) const responseBody = await response.arrayBuffer() res.end(Buffer.from(responseBody)) }) .listen(3000, () => { console.log("Server running at http://localhost:3000/") }) .on("close", () => { dispose() }) ```