Algumas APIs aceitam filtros, seleção de campos e ordenação escritos na própria URL, com uma sintaxe padronizada. Uma condição escrita de forma errada faz o serviço recusar a consulta antes de devolver qualquer dado, e essa recusa pode ser confundida com a falta de registros.
O padrão
O OData é um protocolo para consultar e alterar dados por HTTP, criado pela Microsoft e padronizado pela OASIS, uma organização de padrões abertos. O protocolo segue a organização por recursos do REST e acrescenta convenções para as consultas, para a descrição dos dados e para o formato das respostas.
As opções de consulta começam com o sinal $:
$filter: seleciona os registros que atendem a uma condição;$select: escolhe os campos devolvidos;$expand: inclui dados relacionados, como os itens de um pedido;$orderby: ordena o resultado;$top: limita a quantidade de registros;$skip: pula uma quantidade de registros.
Uma consulta junta essas opções na query string:
GET /odata/Pedidos?$filter=Status eq 'ABERTO'&$select=Numero,Valor&$top=10: pede até dez pedidos com a situação ABERTO e devolve só o número e o valor de cada um.
A condição usa operadores abreviados do inglês, como eq, igual, ne, diferente, gt, maior, e lt, menor. Na URL enviada, os espaços da condição aparecem codificados, como %20. Cada opção só funciona com os nomes de campos definidos no modelo do serviço.
Como reconhecer o OData
Alguns sinais indicam o padrão:
- o trecho
/odata/no caminho; - um registro identificado entre parênteses, como em
Produtos(123); - as opções de consulta iniciadas por
$; - os campos de controle na resposta, como
@odata.context, a partir da versão 4; - os campos
deresultsenvolvendo os dados, nas versões antigas.
O padrão aparece em plataformas corporativas de gestão, como as da SAP e o Microsoft Dynamics. Um parâmetro iniciado por $, sozinho, não confirma o OData, porque um serviço pode adotar nomes parecidos por conta própria.
Erros, paginação e modelo
Um erro de sintaxe, uma propriedade inexistente ou uma opção não suportada costumam receber o código 400, com detalhes no corpo. Uma consulta recusada não executou o filtro, e por isso não informa nada sobre a existência dos registros.
A resposta também pode vir paginada. A partir da versão 4, o campo @odata.nextLink traz o endereço da próxima página, e o caminho correto é seguir esse endereço, e não montar um deslocamento por conta própria. A opção $top=10 limita a quantidade pedida e não informa quantos registros existem no conjunto inteiro.
O endereço $metadata, quando disponível e autorizado, publica o modelo do serviço, com os nomes, os tipos e os relacionamentos dos dados. Uma propriedade removida ou um tipo alterado no modelo pode invalidar uma consulta que antes era aceita. O uso do OData não garante que todos os servidores aceitem as mesmas funções e opções, e por isso a versão do protocolo e do modelo faz parte da análise.
No suporte
Diante de uma consulta OData com problema, convém conferir a versão do protocolo, as propriedades do modelo, as opções aceitas pelo serviço e o texto do erro. Um filtro válido sem resultado e um filtro recusado antes da execução são situações diferentes.
Para guardar
- O OData padroniza consultas e operações sobre recursos, com opções iniciadas por
$. - As opções aceitas e os nomes dos campos dependem do modelo publicado pelo serviço.
- Uma consulta recusada por sintaxe não informa nada sobre a existência dos registros.
- A resposta pode ser paginada, e o
@odata.nextLinkindica a continuação.
Uma URL usa $filter e $top. O que isso sugere?
Sugere OData, principalmente quando aparecem outras convenções do padrão, como o trecho /odata/ e o campo @odata.context. A documentação e a versão confirmam, porque um serviço pode adotar parâmetros parecidos por conta própria.
O retorno informa uma propriedade desconhecida na opção $select. Isso significa que não há pedidos?
Não. O serviço recusou a consulta por causa de um campo não reconhecido, e o filtro nem chegou a ser executado. O nome do campo é conferido no modelo antes de qualquer conclusão sobre os pedidos.