Turn an API JSON Response Into TypeScript Types

The problem

You copied one API JSON response into a type generator. The draft compiled. The next response omitted email or added meta, and TypeScript complained. The generator did not lie. It marked every key it saw as required. You treated one body as the contract.

This solution is how to turn an API JSON response into TypeScript types without that trap. It is not a tutorial on clicking Generate. It is the diagnosis when the second payload does not match the first interface.

Why the next response fails

Inference walks one parsed value. Keys that are present become required properties. Keys that are absent cannot be guessed as optional. Nested objects become extra interfaces. Empty arrays become unknown[]. Mixed array items become unions. Similar objects in one array may emit two interfaces instead of one shared name.

JSON numbers are numbers. The draft will not emit integer. null in the sample becomes an explicit null, not “optional.” Those are different TypeScript forms.

Inspect the sample first

If the body might not be JSON, validate it. If you cannot see nesting, follow how to work with nested JSON: open the JSON Viewer or list paths with the JSON Key Extractor. You need to know which fields appear before you decide which ones are required. Pretty-print alone will not give you that list. The usual order is in how to format, validate and minify JSON when the string is still suspect.

Infer, then edit optionals

Paste the sample into JSON to TypeScript. Copy the interfaces. Then edit:

1. Add ? to properties that real responses omit.
2. Widen a union if a field is sometimes a string and sometimes null.
3. Rename noisy RootItem / RootItem2 pairs when you know they are the same shape.
4. Do not add fields the sample never showed unless you saw them on another response.

The tool will not do those edits. Optional fields are not guessed. That is the feature that keeps the draft honest.

Confirm with a second payload

Keep the first body. Paste a second response — ideally one that omits a field you marked optional and includes a field you left required. If the second body is still JSON and your edited types reject it, either the API drifted or you marked the wrong keys required. Fix the types, or fix the producer. Do not regenerate from the first body and call the job done.

If you only have one fixture, say so in the pull request. “Inferred from checkout.json, email marked optional by hand” is a true statement. “These are the API types” is not.

When not to infer from one body

If the endpoint returns different shapes per status code, one sample is one branch. If the array mixes record types, the union may be noisy. If you need a runtime check, generate a schema and validate instances — types are erased. If the payload is larger than the node budget, the tool clears the output. There is no half-interface to paste.

Do not paste production tokens into a tab you will leave open. Inference runs in the browser. The body still sits there until you clear it.

When the second response matches the edited interfaces, you are done. When it does not, the failure is the diagnosis, not a reason to disable strict.