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.

7 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/httpapi/HttpApi": "~effect/httpapi/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/httpapi/HttpApi": "~effect/httpapi/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/httpapi/HttpApi/AdditionalSchemas", readonly Array<Constraint>, this> {
  constructor(_: never);
}