An Old Problem for Managers: How We Let AI Take Over Hand-Written Types for API Collaboration

Anyone who has led a team has probably been through this conversation:

Before a joint debugging session with a third-party API, the frontend asks the backend: "What type is this field? Can it be null?" The backend digs out the integration doc, only to find it was written three months ago and the API has gone through three revisions since. So the backend captures a packet, pastes the real response into the group chat, and the frontend stares at a piece of JSON, guessing at the types.

Everyone has JSON samples; everyone is guessing at type definitions. This is the most common half-finished project in API collaboration: the debt owed by documentation is always repaid during joint debugging.

We're a small team of about ten people building a multi-platform product, where a single API response needs its types written three times—once for Web, once for the mini-program, once for the native client. Every API change turns three-way type syncing into a tug of war. And as TypeScript projects multiplied, the labor cost of "hand-writing types" started to become glaring—not because it's hard, but because it's repetitive, tedious, and error-prone.

What AI Can Do Here

Later we handed this task to AI. The process is simple, but the results far exceeded expectations. The stages AI can cover include:

1. Inferring complete type definitions from JSON samples, including nested objects, union types, and nullable fields;
2. Identifying fields that "look fixed in the sample but may actually vary"—for example, if remark is null in the sample, AI suggests marking it as string | null instead of asserting null outright;
3. Generating multi-language versions—one sample produces a TypeScript interface, a Kotlin data class, and a Swift struct simultaneously;
4. Including type guard functions and comments, making runtime validation easier and helping newcomers understand what each field means.

For managers, the most critical point is this: it turns "guessing types"—something that depends on individual experience—into a replicable, standardized process. No matter who does it, output quality stays at a consistent level.

Our Standardized Process

The team's rule now is: for any new API integration, the backend provides a real response sample, the frontend doesn't hand-write types, and everything goes through the AI generation pipeline:

Step 1: Sampling. The backend pulls real responses from the test environment—ideally multiple samples covering different states (normal data, empty lists, records containing nulls).

Step 2: Feeding. Hand the samples, along with field descriptions, to AI using a unified prompt template (see below), clearly specifying output format and naming conventions.

Step 3: Review. The frontend spends two or three minutes verifying the AI-generated types—focusing on whether the inferences for union types and optional fields are reasonable. This step cannot be skipped: if AI infers one nullable field wrong, that's a null pointer at runtime.

Step 4: Commit. The type files go into the version repository with field comments preserved, serving as the team's shared "living documentation."

A Replicable Prompt Template

This is the template we use internally—just swap in your own sample:

你是一名资深后端工程师。请根据下面的接口返回 JSON 样例，反推 TypeScript 类型定义。

要求：
1. 输出 interface 定义，字段名保持与 JSON 一致，命名采用 camelCase；
2. 样例中出现 null 的字段，标注为「类型 | null」，不要直接断言为 null；
3. 根据字段语义推断可选性：样例中缺失但业务上可能存在的字段，标为可选（?）并在注释中说明假设；
4. 对每个字段添加中文注释，说明推断依据（来自样例值还是业务常识）；
5. 额外输出一个类型守卫函数 isXxx(data: unknown): data is Xxx，用于运行时校验；
6. 最后列出你不确定的字段清单，标注需要人工确认的问题。

接口名称：获取用户订单详情
JSON 样例：
{
  "code": 0,
  "data": {
    "orderId": "A20240601001",
    "amount": 199.00,
    "status": "PAID",
    "remark": null,
    "items": [
      { "skuId": 8821, "title": "无线鼠标", "qty": 2 }
    ]
  }
}

Item 6 is the key constraint we added: make the AI proactively disclose what it's uncertain about. This effectively generates the review checklist along with the types, so the frontend checks those points first—much more efficient. If you need Kotlin or Swift versions, keep items 5 and 6 and just specify the output language.

Before and After

Process-wise: Previously, for a medium-complexity API (twenty-plus fields, three levels of nesting), the frontend spent roughly forty minutes to an hour hand-writing and verifying types—writing it three times across platforms meant half a day of manpower. Now, sampling plus generation plus review takes under ten minutes per platform, and all three platforms' types are generated in one go. More importantly, the process no longer depends on "the person on the team who knows this API best."

Quality-wise: Hand-written types actually have a higher error rate. People tend to "copy types" from a single sample—if remark is null in the sample, they write null, and when the API returns a string after launch, it blows up immediately. With prompt constraints, AI proactively infers union types and optionality, and even lists uncertain fields. Post-launch rework caused by type mismatches has essentially disappeared from our team.

Collaboration-wise: The biggest change is clear boundaries of responsibility. The backend only provides real samples; the frontend only reviews and confirms; the output goes into the version repository and is traceable. When an API changes, you just rerun the process—the type files themselves are the up-to-date API documentation. The packet-captured JSON that used to be scattered across chat logs now has corresponding type definitions preserved as assets.

Risk control-wise: Two things must be emphasized. First, AI output must be reviewed by a human, especially inferences about optionality and union types—AI hasn't seen all the possible states of an API; anything beyond the samples is just a guess, and the guesses must be signed off by people. Second, never paste samples containing real user data into the prompt template—sanitize data before sampling. This is basic discipline for any team using AI tools.

A Few Management Recommendations

• Turn the prompt template into a team asset, stored in shared documentation—no one writes their own version;
• Put type files into the version repository and require code review, bringing AI output into the normal engineering process rather than leaving it on the fringes;
• Periodically audit the confirmation records for AI's "uncertain fields list" to make sure the review step isn't becoming a formality;
• Model API costs count as routine tooling expenses—refer to the official pricing page for specifics, and just attribute them to the relevant projects.

Scenarios like this, where "AI replaces repetitive labor," require minimal investment with immediate, visible returns—perfect as a small team's first step toward building AI work habits. If you want to manage these kinds of model calls under a unified gateway and control usage per project, check out https://api.thistoken.ai/register—register to start trying it out.

---

Every example in this post runs with a single API key — get yours at https://api.thistoken.ai/register and start in minutes.