clickId, affiliateId, …). Use o parâmetro de query expand[] para materializar uma relação como objeto aninhado na mesma resposta, evitando uma segunda chamada.
expand é restrito a uma lista branca por endpoint: cada endpoint declara quais relações podem ser expandidas. Pedir um valor fora dessa lista é rejeitado na validação com 400 parameter_invalid.
expand nunca muda o recurso retornado: só adiciona campos. Um recurso sem expand e o mesmo recurso com expand têm exatamente os mesmos campos base; o expand apenas acrescenta o objeto da relação.Sintaxe
expand é um parâmetro repetível. Para expandir mais de uma relação, repita a chave:
?expand=click) também é aceito e normalizado internamente para uma lista de um item. As duas formas abaixo são equivalentes:
string[]
Lista de relações a materializar na resposta. Cada endpoint aceita apenas os valores da sua lista branca; um valor fora dela retorna
400 parameter_invalid. Default: [] (nenhuma relação expandida).Endpoints que suportam expand
O padrão é uniforme: endpoints de leitura de um recurso (GET /<recurso>/{id}) declaram as relações que sabem resolver. Os endpoints atualmente expansíveis:
Para saber exatamente quais valores um endpoint aceita, consulte a aba Referência da API do endpoint: a lista branca é declarada lá. Pedir um valor não suportado retorna um erro de validação claro, então é seguro tentar.
Resposta com objetos aninhados
Quando você expande uma relação, o objeto completo daquela relação é embutido na resposta sob uma chave de nome igual ao valor deexpand. Sem expand, a chave simplesmente não aparece (você ainda tem o ID, p.ex. clickId).
GET /payouts/{id}?expand=commissions, o campo commissions carrega a lista de comissões agregadas naquele payout:
expand=commissions
Como o expand resolve as relações
O fluxo é o mesmo em todos os endpoints: a resposta base é montada primeiro; cada valor deexpand aceito dispara a busca da relação correspondente, escopada à mesma organização do recurso.
Por ser escopado à organização, o expand nunca atravessa tenants: você só vê relações que pertencem à sua própria organização.
Boas práticas
Use expand para evitar chamadas N+1
Use expand para evitar chamadas N+1
Ao listar e detalhar conversões, expandir
affiliate na chamada de detalhe poupa uma ida ao endpoint de afiliados. Expanda apenas o que vai usar: cada relação expandida é uma busca adicional no servidor.Trate relações opcionais como nulas
Trate relações opcionais como nulas
Campos como
click em uma conversão podem ser null quando a atribuição não envolveu clique (p.ex. atribuição por cupom). Programe defensivamente para esse caso.Não dependa de expand para campos base
Não dependa de expand para campos base
Os IDs de relação (
clickId, affiliateId, …) sempre estão presentes na resposta base. Use expand só quando precisar do objeto inteiro; caso contrário, o ID basta para uma busca posterior.Próximos passos
IDs e recursos
Como os identificadores com prefixo + ULID identificam cada relação.
Paginação
Liste recursos por cursor antes de detalhar e expandir um deles.
Conversões e fraude
O recurso de conversão e suas relações com clique e afiliado.
Payouts
O payout e as comissões agregadas que você pode expandir.