Convenções das Requests - Filtros e Busca
Veja como funcionam as requests da API do My Turn.
Convenções das Requests - Filtros e Busca
A API do My Turn utiliza-se dos próprios atributos do objeto + operadores de comparação/condição para oferecer filtros e buscas robustas em todas as requests de listagem.
Isso permite que você construa queries avançadas de forma simples, utilizando operadores padronizados.
Parâmetro filter
O parâmetro filter deve ser enviado como objeto de query string, representando os critérios de busca.
Exemplo de request:
https://myturn.com.br/api/public/v1/sellers?filter[name_cont]=ana
Operadores Suportados
Os operadores suportados para construir filtros são:
| Operador | Descrição | Exemplo |
|---|---|---|
_eq | Igual a | filter[id_eq]=10 |
_not_eq | Diferente de | filter[status_not_eq]=inactive |
_cont | Contém (case-insensitive) | filter[name_cont]=ana |
_start | Começa com | filter[name_start]=Jo |
_end | Termina com | filter[email_end]=.com |
_lt | Menor que | filter[age_lt]=18 |
_lteq | Menor ou igual a | filter[created_at_lteq]=2025-01-01 |
_gt | Maior que | filter[age_gt]=30 |
_gteq | Maior ou igual a | filter[updated_at_gteq]=2025-01-01 |
_in | Dentro de uma lista de valores | filter[id_in]=1,2,3 |
_not_in | Fora de uma lista de valores | filter[id_not_in]=4,5,6 |
_present | Valor presente (não nulo e não vazio) | filter[name_present]=true |
_null | Valor nulo | filter[deleted_at_null]=true |
Combinação de Filtros
Você pode combinar múltiplos filtros na mesma request:
https://myturn.com.br/api/public/v1/sellers?filter[name_cont]=ana&filter[status_eq]=active
Operadores de Busca em Registros Relacionados
A API do My Turn permite aplicar filtros em atributos de registros relacionados utilizando a notação de associação seguida do operador desejado.
Suponha que cada seller pertença a uma store. É possível buscar vendedores pelo nome da loja:
https://myturn.com.br/api/public/v1/sellers?filter[store_name_cont]=shopping
Esse request retornará todos os vendedores cuja loja contenha a palavra shopping no nome.
Boas práticas:
Sempre utilize operadores explícitos (ex: _cont, _eq) para maior clareza e previsibilidade.
Consulte a documentação oficial do Ransack para a lista completa de operadores suportados.