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:

region	instances.1.name	instances.1.size	instances.1.name
US	instance1	large	instance2

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:

region	name	size
US	instance1	large
US	instance2	small

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.