Multi-Homing

Imagine you could list all the pokémons on a given pokédex, e.g. pokédex/1/pokemons. It would be tempting for this collection endpoint to return a list of pokémons that are nested within that one pokédex.

GET /pokedex/1/pokemons

{
  "data": [
    {
      "path": "/pokedex/1/pokemons/pikachu"
    },
    {
      "path": "/pokedex/1/pokemons/bulbasaur"
    },
    ...
  ]
}

The problem with this approach is that Unito would now consider pokémons from different pokédexes as being completely different pokémons. Remember, paths are what's used to uniquely identify an item across our ecosystem. Here, we need Unito to understand that one pokémon can be part of multiple pokédexes — they are multi-homed. For this, we need to update the paths so that two pokédexes can point to the same instance of a pokémon.

GET /pokedex/1/pokemons

{
  "data": [
    {
      "path": "/pokemons/pikachu"
    },
    {
      "path": "/pokemons/bulbasaur"
    },
    ...
  ]
}