Esta página tem como objetivo orientar no uso do OData de forma simples e eficaz.
Consultas
As rotas da API pública podem ser consultadas utilizando OData, que é um protocolo padronizado para simplificar o consumo de APIs REST. Para a maioria das consultas, os principais parâmetros para conhecer são os seguintes:
- $filter
- $orderby
- $skip
- $top
IMPORTANTE: Todas as consultas retornam, no máximo, 100 registros por requisição.
Filtro
Para filtrar as informações em uma rota, você deve utilizar o parâmetro $filter. Veja este primeiro exemplo de uma consulta de Usuários com o filtro $filter=name eq 'lucas', retornando os valores que possuem nome igual a lucas:
https://api.nibo.com.br/accountant/api/v1/accountingfirms/a15a25ce-e8fe-4848-aa20-9d8d92c7c93d/users?$filter=name eq 'lucas'
Veja este exemplo de requisição utilizando filtros aplicados: retorna apenas usuários não administradores, com nome exatamente igual a 'joão' e e-mail que começa com 'joão@gmail'.
https://api.nibo.com.br/accountant/api/accountingfirms/a15a25ce-e8fe-4848-aa20-9d8d92c7c93d/users?$filter=isAdmin eq false and name eq 'joão' and startswith(email, 'joão@gmail')
Paginação
As consultas (GET) retornam os parâmetros totalAllItems contendo o número de todos os registros encontrados e total que representa o número de registros encontrados após aplicar os filtros, e você pode utilizar os parâmetros $top, $skip e $orderby para realizar a paginação.
Neste exemplo, temos os parâmetros $top=10, $skip=20 e $orderby=name para indicar que o retorno deverá ser da terceira página, contendo 10 itens por página e ordenado alfabeticamente pelo nome do usuário.
https://api.nibo.com.br/accountant/api/accountingfirms/a15a25ce-e8fe-4848-aa20-9d8d92c7c93d/users?$filter=isAdmin eq true&$orderby=name&$skip=20&$top=10
Juntando tudo
Veja este exemplo de uma consulta de Usuários:
$filter=isAdmin eq true- Filtra apenas usuários administradores.$top=20- Tamanho da página (20 itens).$skip=0- Página 1 (não pulou itens de páginas anteriores).$orderby=name- Ordenado alfabeticamente pelo nome.
https://api.nibo.com.br/accountant/api/accountingfirms/a15a25ce-e8fe-4848-aa20-9d8d92c7c93d/users?$filter=isAdmin eq true&$orderby=name&$top=20&$skip=0
Como usar o OData
O OData oferece recursos robustos para consultas flexíveis e eficientes, permitindo criar requisições altamente personalizáveis. Com sua sintaxe padronizada, você pode construir consultas que combinam filtros avançados para extrair dados precisos.
O OData garante desempenho consistente mesmo com grandes volumes. Essa combinação de recursos permite que cada requisição retorne exatamente o necessário, no formato mais adequado para seu cenário.
Explore todos os operadores, sintaxes avançadas e padrões recomendados na documentação oficial completa em odata.org, onde você encontrará exemplos práticos e orientações detalhadas para o uso.