Clean a JSON API response and type it
Paste the raw body of an API response. The recipe checks that it parses, lays it out with two-space indentation, and writes TypeScript interfaces for every object in it, so the shape of the data is on record before any code is written against it.
The steps
- 1
Validate JSONvia Code Formatter
Stops here with the parse position if the paste is not valid JSON, so a truncated response never goes on to produce wrong types.
- 2
Format JSONvia Code Formatter
Two-space indentation, keys in the order they arrived; this is the copy to drop into a fixture file.
- 3
JSON → TypeScriptvia JSON to TypeScript
Every object becomes an interface named after its key; arrays are typed from their first element.
What the three steps do
The validation step is there to fail early. A response copied out of a browser's network panel is often cut off at the end, or has a trailing comment from a debug proxy, and formatting such a paste produces something that looks fine until the types are wrong. Failing on the first step with the character position is the cheaper outcome.
Formatting comes second so that the intermediate output is readable on its own. The formatted JSON is what most people actually wanted; the interfaces are the bonus. Both are shown, each with its own copy button, and the final output of the run is the TypeScript.
Type generation infers from values. A number is a number, a string is a string, null stays null, and an object nested three levels down gets its own interface. What it cannot know is which fields are optional, because one response shows one shape; treat the result as a first draft and mark the optional fields by hand.
When this comes up
Most often at the start of an integration: you have one real response from a service and no schema document, and you want the compiler on your side before the second endpoint. It also comes up when a response changed under you and the quickest way to see what moved is to regenerate the types and diff them against the old file.
- A webhook payload from a payment or shipping provider, taken from their test mode.
- A GraphQL result you want a plain interface for, without the schema tooling.
- A config blob a colleague sent in chat that needs to become a typed fixture.
What to check in the result
Look for interfaces named after array items, such as ItemsItem, and rename them to something meaningful. Check any field that was null in the sample; it has been typed as null, and the real type is whatever the field holds when it is present. If a key is not a valid identifier, it is quoted in the interface, which is correct but worth knowing.
Questions
- Can it handle a response that is an array at the top level?
- Yes. The root interface then describes one element, and the generator names it after the root name you set. Set the root to the singular noun so the file reads naturally.
- Why did the run stop at validation on a response that works in my app?
- Usually a copy problem rather than a data problem: a trailing character from the network panel, a smart quote from a chat client, or a byte-order mark. Run the paste through the character inspector to see what is there.