Skip to main content

API normalization

A common pattern when interacting with APIs is dealing with nested results. Normalization through the normalize command allows us to expand a key in the results containing nested results into a row perWhat is special about normalization is that it will maintain top level keys in each row, so in this example, each row will also include the top level region key.

Examples

Example 1

Let's take an example where the API response looks like:

{
region: "US",
instances: [
{
name: "instance1",
size: "large",
},
{
name: "instance2",
size: "small",
}
]
}

crul will transform this request into a tabular form:

regioninstances.1.nameinstances.1.sizeinstances.1.name
USinstance1largeinstance2

However, this tabular form is hard to work with, so we could normalize it and transform the results so instance is in a row. What is special about normalization is that it will maintain top level keys in each row, so in this example, each row will also include the top level region key.

We could normalize the instances key by adding a normalize stage.

|| normalize instances

After normalization, our results will look like:

regionnamesize
USinstance1large
USinstance2small

This format is much easier to work with.

Example 1 runnable query

api get https://pokeapi.co/api/v2/pokemon
|| normalize results

This query will first retrieve a list of pokemon from the pokeapi API, however the results are all contained in one row. The results key should be expanded into a row per result. The normalize stage will do this for us.