Expand

A Kruzer oferece o parâmetro de query _expand em suas rotas de listagem e detalhamento para facilitar a expansão de atributos referenciados por identificadores (como ObjectId). Esse recurso permite que os dados relacionados sejam automaticamente populados na resposta, evitando múltiplas chamadas à API e otimizando o consumo dos dados.

O que é expansão?

Em diversos modelos da Kruzer, certos atributos fazem referência a documentos de outras entidades, armazenados apenas como identificadores. Ao utilizar _expand, é possível solicitar que esses atributos sejam substituídos por seus documentos completos no momento da resposta.

Exemplo sem expansão:

GET /orders

Resposta:

[
  {
    "id": "abc123",
    "customer_id": "5f7d3b8a9a3c1c1b9c2b7e4e",
    "product_id": "6a9e8b7c1d2e4f5a6b7c8d9e"
  }
]

Exemplo com expansão de customer_id:

GET /orders?_expand=customer_id

Resposta:

[
  {
    "id": "abc123",
    "customer_id": {
      "id": "5f7d3b8a9a3c1c1b9c2b7e4e",
      "name": "João da Silva",
      "email": "joao@example.com"
    },
    "product_id": "6a9e8b7c1d2e4f5a6b7c8d9e"
  }
]

Expansão Múltipla

Você também pode expandir múltiplos atributos de uma só vez, separando-os por vírgula:

GET /orders?_expand=customer_id,product_id

Essa abordagem é ideal para quando diferentes atributos de uma entidade fazem referência a documentos que você deseja acessar de forma imediata e completa.

Quando usar _expand

Use o _expand quando:

• For necessário exibir dados de entidades relacionadas no mesmo contexto.
• Você deseja evitar múltiplas requisições para buscar entidades referenciadas.
• A resposta da API será usada diretamente para exibição ou enriquecimento de dados no frontend.

Considerações

• Apenas campos previamente configurados como expansíveis na definição do schema serão retornados com seus dados populados.
• A expansão pode afetar a performance em grandes volumes de dados, use com critério.
• A expansão é aplicada após a filtragem e paginação.

---

Com o uso de _expand, a Kruzer oferece uma maneira prática e eficiente de lidar com relacionamentos entre entidades, garantindo respostas mais completas e reduzindo a complexidade das integrações.