Skip to main content Link Search Menu Expand Document (external link)

HttpApi overview

Added in v1.0.0


Table of contents


constructors

make

An HttpApi is a collection of HttpApiEndpoints. You can use an HttpApi to represent a portion of your domain.

The endpoints can be implemented later using the HttpApiBuilder.make api.

Signature

export declare const make: <const Id extends string>(identifier: Id) => HttpApi<Id, never, HttpApiDecodeError>

Added in v1.0.0

guards

isHttpApi

Signature

export declare const isHttpApi: (u: unknown) => u is HttpApi.Any

Added in v1.0.0

models

HttpApi (interface)

An HttpApi is a collection of HttpApiEndpoints. You can use an HttpApi to represent a portion of your domain.

The endpoints can be implemented later using the HttpApiBuilder.make api.

Signature

export interface HttpApi<
  out Id extends string,
  out Groups extends HttpApiGroup.HttpApiGroup.Any = never,
  in out E = never,
  out R = never
> extends Pipeable {
  new (_: never): {}
  readonly [TypeId]: TypeId
  readonly identifier: Id
  readonly groups: Record.ReadonlyRecord<string, Groups>
  readonly annotations: Context.Context<never>
  readonly errorSchema: Schema.Schema<E, unknown, R>
  readonly middlewares: ReadonlySet<HttpApiMiddleware.TagClassAny>

  /**
   * Add a `HttpApiGroup` to the `HttpApi`.
   */
  add<A extends HttpApiGroup.HttpApiGroup.Any>(group: A): HttpApi<Id, Groups | A, E, R>
  /**
   * Add another `HttpApi` to the `HttpApi`.
   */
  addHttpApi<Id2 extends string, Groups2 extends HttpApiGroup.HttpApiGroup.Any, E2, R2>(
    api: HttpApi<Id2, Groups2, E2, R2>
  ): HttpApi<Id, Groups | HttpApiGroup.HttpApiGroup.AddContext<Groups2, R2>, E | E2, R>
  /**
   * Add an global error to the `HttpApi`.
   */
  addError<A, I, RX>(
    schema: Schema.Schema<A, I, RX>,
    annotations?: {
      readonly status?: number | undefined
    }
  ): HttpApi<Id, Groups, E | A, R | RX>
  /**
   * Prefix all endpoints in the `HttpApi`.
   */
  prefix(prefix: PathInput): HttpApi<Id, Groups, E, R>
  /**
   * Add a middleware to a `HttpApi`. It will be applied to all endpoints in the
   * `HttpApi`.
   */
  middleware<I extends HttpApiMiddleware.HttpApiMiddleware.AnyId, S>(
    middleware: Context.Tag<I, S>
  ): HttpApi<
    Id,
    Groups,
    E | HttpApiMiddleware.HttpApiMiddleware.Error<I>,
    R | I | HttpApiMiddleware.HttpApiMiddleware.ErrorContext<I>
  >
  /**
   * Annotate the `HttpApi`.
   */
  annotate<I, S>(tag: Context.Tag<I, S>, value: S): HttpApi<Id, Groups, E, R>
  /**
   * Annotate the `HttpApi` with a Context.
   */
  annotateContext<I>(context: Context.Context<I>): HttpApi<Id, Groups, E, R>
}

Added in v1.0.0

HttpApi (namespace)

Added in v1.0.0

Any (interface)

Signature

export interface Any {
  readonly [TypeId]: TypeId
}

Added in v1.0.0

AnyWithProps (type alias)

Signature

export type AnyWithProps = HttpApi<string, HttpApiGroup.HttpApiGroup.AnyWithProps, any, any>

Added in v1.0.0

reflection

reflect

Extract metadata from an HttpApi, which can be used to generate documentation or other tooling.

See the OpenApi & HttpApiClient modules for examples of how to use this function.

Signature

export declare const reflect: <Id extends string, Groups extends HttpApiGroup.HttpApiGroup.Any, Error, R>(
  self: HttpApi<Id, Groups, Error, R>,
  options: {
    readonly predicate?: Predicate.Predicate<{
      readonly endpoint: HttpApiEndpoint.HttpApiEndpoint.AnyWithProps
      readonly group: HttpApiGroup.HttpApiGroup.AnyWithProps
    }>
    readonly onGroup: (options: {
      readonly group: HttpApiGroup.HttpApiGroup.AnyWithProps
      readonly mergedAnnotations: Context.Context<never>
    }) => void
    readonly onEndpoint: (options: {
      readonly group: HttpApiGroup.HttpApiGroup.AnyWithProps
      readonly endpoint: HttpApiEndpoint.HttpApiEndpoint<string, HttpMethod>
      readonly mergedAnnotations: Context.Context<never>
      readonly middleware: ReadonlySet<HttpApiMiddleware.TagClassAny>
      readonly payloads: ReadonlyMap<string, { readonly encoding: HttpApiSchema.Encoding; readonly ast: AST.AST }>
      readonly successes: ReadonlyMap<
        number,
        { readonly ast: Option.Option<AST.AST>; readonly description: Option.Option<string> }
      >
      readonly errors: ReadonlyMap<
        number,
        { readonly ast: Option.Option<AST.AST>; readonly description: Option.Option<string> }
      >
    }) => void
  }
) => void

Added in v1.0.0

tags

AdditionalSchemas (class)

Signature

export declare class AdditionalSchemas

Added in v1.0.0

Api (class)

Signature

export declare class Api

Added in v1.0.0

type ids

TypeId

Signature

export declare const TypeId: typeof TypeId

Added in v1.0.0

TypeId (type alias)

Signature

export type TypeId = typeof TypeId

Added in v1.0.0