HttpApi

Describes an Effect HTTP API as groups of endpoints.

An HttpApi value is data: it has an identifier, annotations, and groups of endpoints that describe request inputs, responses, middleware, and route metadata. The same description can be used by server builders, generated clients, URL builders, OpenAPI generation, and reflection tools.

14 exports Added in v4.0.0 Source

Constructors

make

Added in v4.0.0 Source

Creates an empty HttpApi with the supplied identifier.

When to use

Use when you need to start defining an HTTP API, add groups with add or addHttpApi, provide endpoint implementations with HttpApiBuilder.group, and register the API with HttpApiBuilder.layer.

Signature

declare function make<Id extends string>(identifier: Id): HttpApi<Id, never>

Guards

isHttpApi

Added in v4.0.0 Source

Returns true when a value is an HttpApi.

Signature

declare function isHttpApi(u: unknown): u is Top

Models

Constraint interface

Added in v4.0.0 Source

An HttpApi value with its identifier and group types erased.

Signature

interface Constraint {
  readonly "~effect/http-api/HttpApi": "~effect/http-api/HttpApi";
}

HttpApi interface

Added in v4.0.0 Source

An HttpApi is a collection of HTTP API groups and endpoints that represents a portion of your domain.

When to use

Use when endpoint implementations can be provided with HttpApiBuilder.group, and the completed API can be registered with HttpApiBuilder.layer.

Signature

interface HttpApi<out Id extends string, in out Groups extends HttpApiGroup.Constraint = never> extends Pipeable {
  constructor(_: never);
  readonly "~effect/http-api/HttpApi": "~effect/http-api/HttpApi";
  readonly annotations: Context<never>;
  readonly groups: GroupMap<Groups>;
  readonly identifier: Id;
  add<A extends readonly [Constraint, Constraint]>(...groups: A): HttpApi<Id, Groups | A[number]>;
  addHttpApi<Id2 extends string, Groups2 extends Constraint>(api: HttpApi<Id2, Groups2>): HttpApi<Id, Groups | Groups2>;
  annotate<I, S>(tag: Key<I, S>, value: S): HttpApi<Id, Groups>;
  annotateMerge<I>(context: Context<I>): HttpApi<Id, Groups>;
  middleware<I extends AnyId, S>(middleware: Key<I, S>): HttpApi<Id, AddMiddleware<Groups, I>>;
  prefix<Prefix extends PathInput>(prefix: Prefix): HttpApi<Id, AddPrefix<Groups, Prefix>>;
}

Top interface

Added in v4.0.0 Source

An HttpApi with broad identifier and group types while retaining the concrete runtime properties used by implementation helpers.

Signature

interface Top extends HttpApi<string, HttpApiGroup.Top> {
  constructor(_: never);
}

Reflection

reflect

Added in v4.0.0 Source

Describes the groups and endpoints in an HttpApi.

Details

The callbacks receive each group or endpoint with merged annotations, endpoint middleware, and response schemas grouped by HTTP status.

Signature

declare function reflect<Id extends string, Groups extends Constraint>(self: HttpApi<Id, Groups>, options: {
  readonly onEndpoint: (options: {
    readonly endpoint: Top;
    readonly errors: ReadonlyMap<number, readonly [Top, Top]>;
    readonly group: Top;
    readonly mergedAnnotations: Context<never>;
    readonly middleware: ReadonlySet<AnyService>;
    readonly successes: ReadonlyMap<number, readonly [Top, Top]>;
  }) => void;
  readonly onGroup: (options: {
    readonly group: Top;
    readonly mergedAnnotations: Context<never>;
  }) => void;
  readonly predicate?: Predicate<{
    readonly endpoint: Top;
    readonly group: Top;
  }>;
}): void

Services

AdditionalSchemas

Added in v4.0.0 Source

Adds additional schemas to components/schemas. The provided schemas must have a identifier annotation.

Signature

declare class AdditionalSchemas extends Shape<"effect/http-api/HttpApi/AdditionalSchemas", readonly Array<Constraint>, this> {
  constructor(_: never);
}

ErrorParseOptions

Added in v4.0.0 Source

Schema parse options for error bodies: server encoding and client decoding. Falls back to ParseOptions when unset.

Signature

declare class ErrorParseOptions extends Shape<"effect/http-api/HttpApi/ErrorParseOptions", ParseOptions, this> {
  constructor(_: never);
}

HeadersParseOptions

Added in v4.0.0 Source

Schema parse options for request headers and the headers of WithHeaders responses: server decoding/encoding and client encoding/decoding, including buffered and streamed responses. Falls back to ParseOptions when unset.

Signature

declare class HeadersParseOptions extends Shape<"effect/http-api/HttpApi/HeadersParseOptions", ParseOptions, this> {
  constructor(_: never);
}

ParamsParseOptions

Added in v4.0.0 Source

Schema parse options for path params: server decoding, client encoding, and HttpApiClient.urlBuilder. Falls back to ParseOptions when unset.

Signature

declare class ParamsParseOptions extends Shape<"effect/http-api/HttpApi/ParamsParseOptions", ParseOptions, this> {
  constructor(_: never);
}

ParseOptions

Added in v4.0.0 Source

Schema parse options for server and client codecs, set on an API, group, or endpoint.

Details

Each codec slot has its own annotation:

ParamsParseOptions for path params
QueryParseOptions for the query string
HeadersParseOptions for request headers and WithHeaders response headers
PayloadParseOptions for request bodies
SuccessParseOptions for success bodies
ErrorParseOptions for error bodies

A slot annotation at any level takes precedence over ParseOptions at any level. If neither is set, Schema defaults apply. Options are replaced, not merged. For the same annotation, endpoint overrides group, which overrides API. Annotate the API before passing it to HttpApiBuilder.group or HttpApiBuilder.endpoint.

Gotchas

Header codecs receive all HTTP headers, including undeclared transport headers such as content-type, content-length, host, user-agent and proxy headers. Without HeadersParseOptions, headers use ParseOptions:

onExcessProperty: "error" rejects real requests and WithHeaders responses with transport headers.
onExcessProperty: "preserve" includes transport headers in the decoded value.

Set HeadersParseOptions to {} at the API level to use Schema defaults for headers, even if an endpoint sets ParseOptions.

Signature

declare class ParseOptions extends Shape<"effect/http-api/HttpApi/ParseOptions", ParseOptions, this> {
  constructor(_: never);
}

Example

(Strict bodies with default header parsing)

import { Schema } from "effect"
import { HttpApi, HttpApiEndpoint, HttpApiGroup } from "effect/http-api"

const api = HttpApi.make("Api")
  .add(
    HttpApiGroup.make("users").add(
      HttpApiEndpoint.post("create", "/users", {
        headers: { "x-api-key": Schema.String },
        payload: { name: Schema.String }
      })
    )
  )
  .annotate(HttpApi.ParseOptions, { onExcessProperty: "error" })
  .annotate(HttpApi.HeadersParseOptions, {})

PayloadParseOptions

Added in v4.0.0 Source

Schema parse options for request bodies, including multipart payloads: server decoding and client encoding. Falls back to ParseOptions when unset.

Signature

declare class PayloadParseOptions extends Shape<"effect/http-api/HttpApi/PayloadParseOptions", ParseOptions, this> {
  constructor(_: never);
}

QueryParseOptions

Added in v4.0.0 Source

Schema parse options for the query string: server decoding, client encoding, and HttpApiClient.urlBuilder. Falls back to ParseOptions when unset.

Signature

declare class QueryParseOptions extends Shape<"effect/http-api/HttpApi/QueryParseOptions", ParseOptions, this> {
  constructor(_: never);
}

SuccessParseOptions

Added in v4.0.0 Source

Schema parse options for success bodies, including streams, SSE events, and the body of WithHeaders responses: server encoding and client decoding. Falls back to ParseOptions when unset.

Signature

declare class SuccessParseOptions extends Shape<"effect/http-api/HttpApi/SuccessParseOptions", ParseOptions, this> {
  constructor(_: never);
}