Hey API

Hey API provides a variety of HTTP clients that are seamlessly integrated with the @hey-api/openapi-ts ecosystem. Instead of forcing a specific technology, Hey API supports multiple client implementations, allowing you to use the one that best fits your project.

Key features include:

• Type-safe response data and errors.
• Response data validation and transformation.
• Access to original requests and responses.
• Granular customization options for requests and responses.
• Support for bundling inside the generated output.
• Minimal learning curve by extending the underlying technology you already use.

When using @hey-api/openapi-ts with default configuration, the generator produces a set of files in your specified output directory. These files include the client, the SDK, and TypeScript types. The structure typically looks like this:

• client.gen.ts: The generated client instance.
• sdk.gen.ts: The generated SDK methods.
• types.gen.ts: The generated TypeScript types.
• index.ts: A convenience entry file that re-exports the generated artifacts.
• client/ and core/ folders: Scaffolding used by client plugins to enable HTTP requests.

Hey API uses a plugin-based architecture where 'Core Plugins' serve as the foundation for all other functionality. These core plugins provide the essential primitives that specialized plugins (like framework-specific adapters) reuse. By building on these core artifacts, Hey API ensures a smaller output size and a more consistent developer experience.

The core plugins include:

• TypeScript: Handles TypeScript-specific generation logic.
• SDK: Manages the generation of the SDK structure.
• Transformers: Handles data transformation logic during the generation process.
• Schemas: Manages the generation and handling of schemas.

The plugin generates types in a types.gen.ts file. These types do not impact bundle size or runtime performance as they are discarded during build time (unless runtime enums are configured).

Generated types include:

• Requests: A single type per endpoint containing body, path, query, and url properties. Customize naming/casing via .name and .case options.
• Responses: A type for all endpoint responses, including a helper type for individual status codes. Customize naming/casing via .name and .case options.
• Definitions: A type for every reusable definition in your OpenAPI spec. Customize naming/casing via .name and .case options.

Hey API provides support for the AIOHTTP asynchronous HTTP client/server for Python. This client is designed to be compatible with all Hey API features.

Note: As of the current documentation, AIOHTTP support is currently marked as planned (Issue #4098).

The Factory Boy plugin for Hey API is designed to integrate with Factory Boy, a fixtures replacement tool based on thoughtbot's factory_bot. It aims to replace static, hard-to-maintain fixtures with easy-to-use factories for complex objects.

Note: This feature is currently marked as planned (Issue #4093) and may not be available in all current versions.

You can install hey-api using uv to add it to your project dependencies, or use uvx to run the CLI tool without a permanent installation.

uv add hey-api

# Or run without installing:
uvx hey-api --help