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.
Constructors
Guards
Models
Constraint interface
An HttpApi value with its identifier and group types erased.
Signature
interface Constraint {
readonly "~effect/httpapi/HttpApi": "~effect/httpapi/HttpApi";
}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>>;
}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
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
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);
}
Creates an empty
HttpApiwith the supplied identifier.When to use
Use when you need to start defining an HTTP API, add groups with
addoraddHttpApi, provide endpoint implementations withHttpApiBuilder.group, and register the API withHttpApiBuilder.layer.