skills.rest
PostHog
PostHogOFFICIAL
Explore all skills by this author →
Website𝕏@PostHogGitHub

adopting-generated-api-types

Migrates frontend code from manual API calls and handwritten types to generated TypeScript API functions.

713|118|Updated Aug 11, 2020
Search Tags:#OpenAPI#Refactoring#Type Safety#typeScript#PostHog#api migration#Code generation
One-click install
npx skills add https://github.com/PostHog/posthog-foss --skill adopting-generated-api-types
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: adopting-generated-api-types
Source: https://github.com/PostHog/posthog-foss/tree/main/.agents/skills/adopting-generated-api-types
Command: npx skills add https://github.com/PostHog/posthog-foss --skill adopting-generated-api-types

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

PostHog's frontend contains thousands of manual API calls (api.get, api.create, api.surveys.get, new ApiRequest()) and handwritten TypeScript interfaces that duplicate backend serializers, causing type drift and maintenance burden. This Skill guides the systematic replacement of these legacy patterns with type-safe functions generated from Django serializers via the OpenAPI pipeline.

Core Features & Use Cases

  • Pattern Detection and Replacement: Identifies all three legacy patterns (high-level object API, raw HTTP methods with manual URLs, and the ApiRequest builder) and maps each to its generated equivalent like surveysRetrieve or domainsCreate.
  • Type Migration Guidance: Explains differences between handwritten types and generated Api-suffixed types, covering readonly fields, Patched variants, pagination wrappers, nullable vs optional fields, and enum conventions.
  • Decision Framework: Provides a decision table for scenarios where generated functions or types are missing, directing developers to fix backend @extend_schema annotations first rather than force-migrating.
  • Use Case: While editing a Kea logic file that calls api.surveys.list(), replace it with surveysList(projectId, params), swap Survey for SurveyApi, remove the dead handwritten type, and verify with pnpm --filter=@posthog/frontend typescript:check.

Quick Start

Ask the AI to migrate the manual API calls in the current frontend file to generated API functions and types.

Frequently Asked Questions about adopting-generated-api-types

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I migrate api.surveys.get() to generated API functions?▼

Replace `api.surveys.get(id)` with `surveysRetrieve(String(projectId), id)` imported from `products/surveys/frontend/generated/api`. Generated functions take projectId explicitly as the first argument, unlike the high-level API which pulls it from context.

How do I replace handwritten TypeScript types with generated API types?▼

Import the generated type with the `Api` suffix from `api.schemas.ts`, such as `import type { SurveyApi } from 'products/surveys/frontend/generated/api.schemas'`. Update all usage sites, then delete the handwritten type and run the TypeScript check.

What if no generated function exists for a custom API action?▼

Keep the manual call in place and fix the backend first by adding `@extend_schema` to the `@action`, then regenerate with `hogli build:openapi`. Do not force-migrate calls that lack generated equivalents.

Why does TypeScript error on readonly fields after migrating to generated types?▼

Generated types mark serializer read-only fields as `readonly`, so direct mutation fails. Spread the response into a new object for local mutation, or use `Patched*Api` types when building partial update payloads.

Does switching to generated API functions change HTTP behavior?▼

No. Generated functions wrap the same `api` module through `api-orval-mutator.ts`, preserving cookies, CSRF handling, and error behavior. Only type safety and URL construction change.

Related Skills

Explore More Software Engineering Skills→
jammindevjammindev

gen-api

Regenerate TypeScript API client types from a Django OpenAPI schema.

Official
Intermediate
jchildreejchildree
1

migrate-to-shoehorn

Migrate TypeScript test assertions from 'as' to Shoehorn's 'fromPartial', 'fromAny', and 'fromExact' functions.

Community
Intermediate
PostHogPostHog
693

improving-drf-endpoints

Audit Django REST Framework viewsets and serializers for type safety and OpenAPI documentation.

Official
Advanced
vafastvafast

CLI 工具 - Vafast

Automates Vafast API type synchronization by generating TypeScript files from a server URL and output path.

Official
Intermediate