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

ApiEndpoint overview

HTTP endpoint declaration.

Added in v1.0.0

Table of contents

constructors

delete

Signature

export declare const delete: <Id extends ApiEndpoint.AnyId>(id: Id, path: HttpRouter.PathInput, options?: Partial<Options>) => ApiEndpoint.Default<Id>

Added in v1.0.0

get

Signature

export declare const get: <Id extends ApiEndpoint.AnyId>(
  id: Id,
  path: HttpRouter.PathInput,
  options?: Partial<Options>
) => ApiEndpoint.Default<Id>

Added in v1.0.0

make

Signature

export declare const make: <Id extends ApiEndpoint.AnyId>(
  method: HttpMethod.HttpMethod,
  id: Id,
  path: HttpRouter.PathInput,
  options?: Partial<Options>
) => ApiEndpoint.Default<Id>

Added in v1.0.0

patch

Signature

export declare const patch: <Id extends ApiEndpoint.AnyId>(
  id: Id,
  path: HttpRouter.PathInput,
  options?: Partial<Options>
) => ApiEndpoint.Default<Id>

Added in v1.0.0

post

Signature

export declare const post: <Id extends ApiEndpoint.AnyId>(
  id: Id,
  path: HttpRouter.PathInput,
  options?: Partial<Options>
) => ApiEndpoint.Default<Id>

Added in v1.0.0

put

Signature

export declare const put: <Id extends ApiEndpoint.AnyId>(
  id: Id,
  path: HttpRouter.PathInput,
  options?: Partial<Options>
) => ApiEndpoint.Default<Id>

Added in v1.0.0

getters

getMethod

Signature

export declare const getMethod: <
  Id extends ApiEndpoint.AnyId,
  Request extends ApiRequest.ApiRequest.Any,
  Response extends ApiResponse.ApiResponse.Any,
  Security extends Security.Security.Any
>(
  endpoint: ApiEndpoint<Id, Request, Response, Security>
) => HttpMethod.HttpMethod

Added in v1.0.0

getOptions

Signature

export declare const getOptions: <
  Id extends ApiEndpoint.AnyId,
  Request extends ApiRequest.ApiRequest.Any,
  Response extends ApiResponse.ApiResponse.Any,
  Security extends Security.Security.Any
>(
  endpoint: ApiEndpoint<Id, Request, Response, Security>
) => Options

Added in v1.0.0

getPath

Signature

export declare const getPath: <
  Id extends ApiEndpoint.AnyId,
  Request extends ApiRequest.ApiRequest.Any,
  Response extends ApiResponse.ApiResponse.Any,
  Security extends Security.Security.Any
>(
  endpoint: ApiEndpoint<Id, Request, Response, Security>
) => HttpRouter.PathInput

Added in v1.0.0

getRequest

Signature

export declare const getRequest: <
  Id extends ApiEndpoint.AnyId,
  Request extends ApiRequest.ApiRequest.Any,
  Response extends ApiResponse.ApiResponse.Any,
  Security extends Security.Security.Any
>(
  endpoint: ApiEndpoint<Id, Request, Response, Security>
) => Request

Added in v1.0.0

getResponse

Signature

export declare const getResponse: <
  Id extends ApiEndpoint.AnyId,
  Request extends ApiRequest.ApiRequest.Any,
  Response extends ApiResponse.ApiResponse.Any,
  Security extends Security.Security.Any
>(
  endpoint: ApiEndpoint<Id, Request, Response, Security>
) => ReadonlyArray<Response>

Added in v1.0.0

getSecurity

Signature

export declare const getSecurity: <
  Id extends ApiEndpoint.AnyId,
  Request extends ApiRequest.ApiRequest.Any,
  Response extends ApiResponse.ApiResponse.Any,
  Security extends Security.Security.Any
>(
  endpoint: ApiEndpoint<Id, Request, Response, Security>
) => Security

Added in v1.0.0

isFullResponse

Is used by the client and server implementation to determine whether to use a full { status; body; headers } response or just the body.

The logic is that if there is only one declared response and it doesn’t specify any headers, the simplified version with body only is used, otherwise the full response is used.

Signature

export declare const isFullResponse: <
  Id extends ApiEndpoint.AnyId,
  Request extends ApiRequest.ApiRequest.Any,
  Response extends ApiResponse.ApiResponse.Any,
  Security extends Security.Security.Any
>(
  endpoint: ApiEndpoint<Id, Request, Response, Security>
) => boolean

Added in v1.0.0

setResponse

Signature

export declare const setResponse: <
  Status extends ApiResponse.ApiResponse.AnyStatus,
  Body = ApiSchema.Ignored,
  Headers = ApiSchema.Ignored,
  R = never
>(
  response:
    | {
        readonly status: Status
        readonly body?: Schema.Schema<Body, any, R>
        readonly headers?: Schema.Schema<Headers, any, R>
      }
    | ApiResponse.ApiResponse<Status, Body, Headers, R>
) => <
  Id extends ApiEndpoint.AnyId,
  Request extends ApiRequest.ApiRequest.Any,
  _ extends ApiResponse.ApiResponse.Any,
  Security extends Security.Security.Any
>(
  endpoint: ApiEndpoint<Id, Request, _, Security>
) => ApiEndpoint<Id, Request, ApiResponse.ApiResponse<Status, Body, Headers, R>, Security>

Added in v1.0.0

models

ApiEndpoint (interface)

Signature

export interface ApiEndpoint<
  Id extends ApiEndpoint.AnyId,
  Request extends ApiRequest.ApiRequest.Any,
  Response extends ApiResponse.ApiResponse.Any,
  _Security extends Security.Security.Any
> extends ApiEndpoint.Variance<Id, Request, Response, _Security>,
    Pipeable.Pipeable {}

Added in v1.0.0

ApiEndpoint (namespace)

Added in v1.0.0

Variance (interface)

Signature

export interface Variance<
  Id,
  Request extends ApiRequest.ApiRequest.Any,
  Response extends ApiResponse.ApiResponse.Any,
  Security extends Security.Security.Any
> {
  readonly [TypeId]: {
    readonly _Id: Types.Covariant<Id>
    readonly _Request: Types.Covariant<Request>
    readonly _Response: Types.Covariant<Response>
    readonly _Security: Types.Covariant<Security>
  }
}

Added in v1.0.0

Any (type alias)

Any endpoint with Request = Request.Any and Response = Response.Any.

Signature

export type Any = ApiEndpoint<AnyId, ApiRequest.ApiRequest.Any, ApiResponse.ApiResponse.Any, Security.Security.Any>

Added in v1.0.0

AnyId (type alias)

Any endpoint id.

Signature

export type AnyId = string

Added in v1.0.0

Context (type alias)

Signature

export type Context<Endpoint> = [Endpoint] extends [ApiEndpoint<any, infer Request, infer Response, infer S>]
  ? ApiRequest.ApiRequest.Context<Request> | ApiResponse.ApiResponse.Context<Response> | Security.Security.Context<S>
  : never

Added in v1.0.0

ContextNoSecurity (type alias)

Signature

export type ContextNoSecurity<Endpoint> = [Endpoint] extends [ApiEndpoint<any, infer Request, infer Response, any>]
  ? ApiRequest.ApiRequest.Context<Request> | ApiResponse.ApiResponse.Context<Response>
  : never

Added in v1.0.0

Default (type alias)

Default endpoint spec.

Signature

export type Default<Id extends AnyId> = ApiEndpoint<
  Id,
  ApiRequest.ApiRequest.Default,
  ApiResponse.ApiResponse.Default,
  Security.Security.Default
>

Added in v1.0.0

Error (type alias)

Signature

export type Error<Endpoint> = [Endpoint] extends [ApiEndpoint<any, any, any, infer S>]
  ? Security.Security.Error<S>
  : never

Added in v1.0.0

ExcludeById (type alias)

Signature

export type ExcludeById<Endpoint extends Any, Id extends AnyId> =
  Endpoint extends ApiEndpoint<Id, any, any, any> ? never : Endpoint

Added in v1.0.0

ExtractById (type alias)

Signature

export type ExtractById<Endpoint, Id extends AnyId> = Endpoint extends ApiEndpoint<Id, any, any, any> ? Endpoint : never

Added in v1.0.0

Id (type alias)

Signature

export type Id<Endpoint> = Endpoint extends ApiEndpoint<infer Id, any, any, any> ? Id : never

Added in v1.0.0

Request (type alias)

Signature

export type Request<Endpoint> = Endpoint extends ApiEndpoint<any, infer Request, any, any> ? Request : never

Added in v1.0.0

Response (type alias)

Signature

export type Response<Endpoint> = Endpoint extends ApiEndpoint<any, any, infer Response, any> ? Response : never

Added in v1.0.0

Security (type alias)

Signature

export type Security<Endpoint> = Endpoint extends ApiEndpoint<any, any, any, infer Security> ? Security : never

Added in v1.0.0

Options (interface)

Signature

export interface Options {
  readonly deprecated?: boolean
  readonly description?: string
  readonly summary?: string
}

Added in v1.0.0

modifications

addResponse

Signature

export declare const addResponse: <
  Status extends ApiResponse.ApiResponse.AnyStatus,
  Body = ApiSchema.Ignored,
  Headers = ApiSchema.Ignored,
  R = never
>(
  response:
    | ApiResponse.ApiResponse<Status, Body, Headers, R>
    | {
        readonly status: Status
        readonly body?: Schema.Schema<Body, any, R>
        readonly headers?: Schema.Schema<Headers, any, R>
      }
) => <
  Id extends ApiEndpoint.AnyId,
  Request extends ApiRequest.ApiRequest.Any,
  Response1 extends ApiResponse.ApiResponse.Any,
  Security extends Security.Security.Any
>(
  endpoint: ApiEndpoint<Id, Request, Response1, Security>
) => ApiEndpoint<Id, Request, Response1 | ApiResponse.ApiResponse<Status, Body, Headers, R>, Security>

Added in v1.0.0

getId

Signature

export declare const getId: <
  Id extends ApiEndpoint.AnyId,
  Request extends ApiRequest.ApiRequest.Any,
  Response extends ApiResponse.ApiResponse.Any,
  Security extends Security.Security.Any
>(
  endpoint: ApiEndpoint<Id, Request, Response, Security>
) => Id

Added in v1.0.0

setOptions

Signature

export declare const setOptions: (options: Partial<Options>) => <A extends ApiEndpoint.Any>(endpoint: A) => A

Added in v1.0.0

setRequest

Signature

export declare const setRequest: <Request extends ApiRequest.ApiRequest.Any>(
  request: Request
) => <
  Id extends ApiEndpoint.AnyId,
  _ extends ApiRequest.ApiRequest.Any,
  Response extends ApiResponse.ApiResponse.Any,
  Security extends Security.Security.Any
>(
  endpoint: ApiEndpoint<Id, _, Response, Security>
) => ApiEndpoint<Id, Request, Response, Security>

Added in v1.0.0

setRequestBody

Signature

export declare const setRequestBody: <B, R2>(
  schema: Schema.Schema<B, any, R2>
) => <
  Id extends ApiEndpoint.AnyId,
  _,
  P,
  Q,
  H,
  R1,
  Response extends ApiResponse.ApiResponse.Any,
  Security extends Security.Security.Any
>(
  endpoint: ApiEndpoint<Id, ApiRequest.ApiRequest<_, P, Q, H, R1>, Response, Security>
) => ApiEndpoint<Id, ApiRequest.ApiRequest<B, P, Q, H, R1 | R2>, Response, Security>

Added in v1.0.0

setRequestHeaders

Signature

export declare const setRequestHeaders: <H, I extends Readonly<Record<string, string | undefined>>, R2>(
  schema: Schema.Schema<H, I, R2>
) => <
  Id extends ApiEndpoint.AnyId,
  B,
  P,
  Q,
  _,
  R1,
  Response extends ApiResponse.ApiResponse.Any,
  Security extends Security.Security.Any
>(
  endpoint: ApiEndpoint<Id, ApiRequest.ApiRequest<B, P, Q, _, R1>, Response, Security>
) => ApiEndpoint<Id, ApiRequest.ApiRequest<B, P, Q, H, R1 | R2>, Response, Security>

Added in v1.0.0

setRequestPath

Signature

export declare const setRequestPath: <P, I extends Readonly<Record<string, string | undefined>>, R2>(
  schema: Schema.Schema<P, I, R2>
) => <
  Id extends ApiEndpoint.AnyId,
  B,
  _,
  Q,
  H,
  R1,
  Response extends ApiResponse.ApiResponse.Any,
  Security extends Security.Security.Any
>(
  endpoint: ApiEndpoint<Id, ApiRequest.ApiRequest<B, _, Q, H, R1>, Response, Security>
) => ApiEndpoint<Id, ApiRequest.ApiRequest<B, P, Q, H, R1 | R2>, Response, Security>

Added in v1.0.0

setRequestQuery

Signature

export declare const setRequestQuery: <
  Q,
  I extends Readonly<Record<string, string | undefined | ReadonlyArray<string>>>,
  R2
>(
  schema: Schema.Schema<Q, I, R2>
) => <
  Id extends ApiEndpoint.AnyId,
  B,
  P,
  _,
  H,
  R1,
  Response extends ApiResponse.ApiResponse.Any,
  Security extends Security.Security.Any
>(
  endpoint: ApiEndpoint<Id, ApiRequest.ApiRequest<B, P, _, H, R1>, Response, Security>
) => ApiEndpoint<Id, ApiRequest.ApiRequest<B, P, Q, H, R1 | R2>, Response, Security>

Added in v1.0.0

setResponseBody

Signature

export declare const setResponseBody: <B, R2>(
  schema: Schema.Schema<B, any, R2>
) => <
  Id extends ApiEndpoint.AnyId,
  Request extends ApiRequest.ApiRequest.Any,
  S extends ApiResponse.ApiResponse.AnyStatus,
  _,
  H,
  R1,
  Security extends Security.Security.Any
>(
  endpoint: ApiEndpoint<Id, Request, ApiResponse.ApiResponse<S, _, H, R1>, Security>
) => ApiEndpoint<Id, Request, ApiResponse.ApiResponse<S, B, H, R1 | R2>, Security>

Added in v1.0.0

setResponseHeaders

Signature

export declare const setResponseHeaders: <H, R2>(
  schema: Schema.Schema<H, any, R2>
) => <
  Id extends ApiEndpoint.AnyId,
  Request extends ApiRequest.ApiRequest.Any,
  S extends ApiResponse.ApiResponse.AnyStatus,
  B,
  _,
  R1,
  Security extends Security.Security.Any
>(
  endpoint: ApiEndpoint<Id, Request, ApiResponse.ApiResponse<S, B, _, R1>, Security>
) => ApiEndpoint<Id, Request, ApiResponse.ApiResponse<S, B, H, R1 | R2>, Security>

Added in v1.0.0

setResponseRepresentations

Signature

export declare const setResponseRepresentations: (
  representations: Array.NonEmptyReadonlyArray<Representation.Representation>
) => <
  Id extends ApiEndpoint.AnyId,
  Request extends ApiRequest.ApiRequest.Any,
  Response extends ApiResponse.ApiResponse.Any,
  Security extends Security.Security.Any
>(
  endpoint: ApiEndpoint<Id, Request, Response, Security>
) => ApiEndpoint<Id, Request, Response, Security>

Added in v1.0.0

setResponseStatus

Signature

export declare const setResponseStatus: <Status extends ApiResponse.ApiResponse.AnyStatus>(
  status: Status
) => <
  Id extends ApiEndpoint.AnyId,
  Request extends ApiRequest.ApiRequest.Any,
  _ extends ApiResponse.ApiResponse.AnyStatus,
  B,
  H,
  R,
  Security extends Security.Security.Any
>(
  endpoint: ApiEndpoint<Id, Request, ApiResponse.ApiResponse<_, B, H, R>, Security>
) => ApiEndpoint<Id, Request, ApiResponse.ApiResponse<Status, B, H, R>, Security>

Added in v1.0.0

setSecurity

Signature

export declare const setSecurity: <Security extends Security.Security.Any>(
  security: Security
) => <
  Id extends ApiEndpoint.AnyId,
  Request extends ApiRequest.ApiRequest.Any,
  Response extends ApiResponse.ApiResponse.Any,
  _ extends Security.Security.Any
>(
  endpoint: ApiEndpoint<Id, Request, Response, _>
) => ApiEndpoint<Id, Request, Response, Security>

Added in v1.0.0

refinements

isApiEndpoint

Signature

export declare const isApiEndpoint: (u: unknown) => u is ApiEndpoint.Any

Added in v1.0.0

type id

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