Pagination

Pagination is optional. When realistic, connectors can decide to always return the entire dataset as part of a single collection page, even if that means issuing multiple calls to their underlying provider to retrieve all that data. This is mostly useful when the list of items is bounded and known in advance to be relatively small.

Without pagination

As an example, we might want to provide a way to list the moves available for a given pokémon. Knowing that the list will always be limited to a few items, our connector might decide to always return the full collection without bothering with pagination, no matter how many moves each pokémon has.

GET /pokemons/Bulbasaur/moves?select=name,type

{
  info: {},
  data: [
    {
      path: "/moves/growl",
      fields: { name: "Growl", type: "NORMAL" },
    },
    {
      path: "/moves/tackle",
      fields: { name: "Tackle", type: "NORMAL" },
    },
    {
      path: "/moves/vine-whip",
      fields: { name: "Vines Whip", type: "GRASS" },
    },
    {
      path: "/moves/growth",
      fields: { name: "Growth", type: "NORMAL" },
    },
    [...]
    {
      path: "/moves/solar-beam",
      fields: { name: "Solar Beam", type: "GRASS" },
    }
  ]
}

With pagination

More often than not though, it makes more sense to paginate the results. Unito doesn't prescribe any particular pagination strategy, nor will it ever request an arbitrary page or a specific number of items per page.

All that is asked of connectors is that each page provides a link to the next page. This link will be followed as is whenever Unito needs to load more data, which means it needs to contain everything it requires to keep iterating on the exact same dataset, including any query parameters that might have been sent as part of the original request.

warning

If there are remaining items, the connector must return a path to the next page, including the necessary query parameters to keep working with the same dataset and receive the same fields.

For example, since we initially requested for the name and type for all moves of type GRASS, we expect the next page to respect these constraints too.

GET /moves?select=name,type,pokemons&filters=type%3DGRASS

{
  info: {
    nextPage: "/moves?page=2&limit=5&select=name,type,pokemons&filters=type%3DGRASS"
  }
  data: [
    {
      path: "/moves/vine-whip",
      fields: { name: "Vines Whip", type: "GRASS", pokemons: [bulbasaur, ...] },
    },
    {
      path: "/moves/leech-seed",
      fields: { name: "Leech Seed", type: "GRASS", pokemons: [bulbasaur, ...] },
    },
    {
      path: "/moves/razor-leaf",
      fields: { name: "Razor Leaf", type: "GRASS", pokemons: [bulbasaur, ...] },
    },
    {
      path: "/moves/seed-bomb",
      fields: { name: "Seed Bomb", type: "GRASS", pokemons: [bulbasaur, ...] },
    },
    {
      path: "/moves/solar-beam",
      fields: { name: "Solar Beam", type: "GRASS", pokemons: [bulbasaur, ...] },
    }
  ]
}