Skip to content

Libraries · Reference

HttpApi Adapter

A shared Effect service for HTTP API operation discovery, generated client execution, and result encoding for CLI and toolkit adapters.

Last updated October 9, 2026

Overview

HttpApiAdapter is the shared foundation for CLI and AI toolkit adapters, including toolkits registered with MCP. One service owns the selected operation catalogue, generated HTTP client execution, and result encoding. Input and success codecs are reflected together from the same API, so discovery and execution cannot be configured against different APIs.

operations contains names, original group and endpoint identifiers, reflected inputSchema, derived inputJsonSchema, success codecs, and method annotations. OpenAPI provides presentation metadata; generated client dispatch uses original endpoint identifiers, including when an endpoint has a custom OpenAPI operation ID.

Install

shell
bunx shadcn@latest add @krak-stack/httpapi-adapter

Installation And Imports

Install @krak-stack/registry and import @krak-stack/registry/httpapi/adapter. Alternatively, install @krak-stack/httpapi-adapter with shadcn and import @/lib/httpapi-adapter. ApiClient, HttpApiSpec, and the old client/helper package subpaths have been replaced by this service.

Configure Once

ts
import { Layer } from "effect";
import { FetchHttpClient } from "effect/http";
import { HttpApiAdapter } from "@krak-stack/registry/httpapi/adapter";
import { AppApi } from "@/api";

export const adapterLayer = HttpApiAdapter.layer({
  api: AppApi,
  baseUrl: "https://example.com",
  methods: ["get"],
}).pipe(Layer.provide(FetchHttpClient.layer));

Provide adapterLayer to makeHttpApiCli() or makeHttpApiToolkit(). Use include to narrow operations further. All supported methods are included when methods is omitted, so explicitly select GET operations for read-only exposure. Method selection and annotations are not authorization. Provide an app-owned authenticated HttpClient when the downstream API requires credentials.

Inputs And Results

Inputs use { params, query, headers, body }. Path, query, and header values use decoded endpoint types: pass { query: { days: 7 } }, not a wire string. Payload codecs preserve transformations such as decoding an ISO string into a Date. The generated Effect HttpApiClient handles wire encoding and response decoding.

adapter.execute({ operation, input }) supplies empty parameter, query, and header maps when omitted, and only executes operations in its catalogue. Validate untrusted input with the operation's inputSchema first; CLI and toolkit adapters do this at their boundaries. adapter.encodeResult(result, operation) uses the reflected success codec before JSON normalization. Override encodeResult in the layer configuration when an application requires custom serialization. Keep application API definitions, authentication, and handlers application-owned.

Dependencies
Packages and shadcn components required by this registry item.

Dependencies