Conhecendo o protocolo OData

Vamos falar nesse artigo sobre mais uma “ferramenta” que deve ser considerada em seus projetos.

O OData (Open Data Protocol) é um padrão OASIS (Organization for the Advancement of Structured Information Standards), que define um conjunto aprovado pela ISO/IEC que rege um conjunto de melhores práticas para construir e consumir APIs RESTful.

Basicamente o protocolo OData inclui em sua API “recursos extras” que permitem que sua implementação torne seus “endpoints” consultáveis e interoperáveis.

OData não é uma tecnologia recente, já está a um bom tempo no mercado, mas não é muito difundida, eu tive conhecimento dela a pouco tempo como alternativa para um projeto que estou trabalhando.

Podemos através deste protocolo por exemplo resolver o problema de “over-fetching” que é trazer mais dados do que se precisa em uma requisição.

O conceito de “over-fetching” é também uma das grandes vantagens do GraphQL(veja aqui neste meu artigo).

A Microsoft já disponibiliza bibliotecas para trabalhar com o OData simplificando todo o processo.

Para o entendimento desta tecnologia vamos elaborar um exemplo bem simples usando inclusive o mesmo modelo de projeto dos dois artigos anteriores, um cliente que possui ordens no mercado de ações.

O projeto deste artigo se encontra no meu github.

–Configurando a aplicação–

Basicamente vamos ter uma API na versão 5 do .net core, para trabalhar com o OData basta baixar o seguinte pacote nuget

pacote nuget

Precisamos habilitar o OData no Startup da aplicação:

Alteração na classe Startup.cs

Inclui ali na linha 4 a chamada ao interceptador do OData.

Vou utilizar dados “mockados” para a implementação. Basicamente nossa fonte de dados será a classe CustomerServices:

Não se preocupe esse código está no meu github pronto para uso (nesta imagem temos 4 clientes mockados porém no código temos 20)

O código do controller é muito simples:

Controller

O atributo [EnabledQuery] ali na linha 12 permite que o endpoint seja consultado usando a sintaxe do protocolo OData.

–Consultando os dados–

Pronto com essas simples configurações já podemos começar a “brincar” com o protocolo OData.

Antes vamos entender como funciona as convenções do OData que basicamente são comandos que você pode passar na URL.

Uma URL do OData é composta por três partes: a URL base do serviço, o caminho do recurso e as opções de consulta (conhecidas como Query Options).

As principais “query options” do OData são:

  • $select: seleciona as colunas ou propriedades especificas no conjunto de resultados;
  • $expand: Permite expandir as entidades filhas de um domínio;
  • $orderby: Classifica os resultados buscado em uma ordem específica, como crescente ou decrescente;
  • $top: busca apenas os n principais registros. Por exemplo, eu quero buscar os 10 principais registros do banco de dados;
  • $skip: use para pular o número de registros ou resultados. Por exemplo, quero pular os primeiros 100 registros do banco de dados no retorno de minha consulta;
  • $count: retorna a quantidade de itens que resultariam dessa consulta;
  • $search: possibilita uma pesquisa de texto livre sobre o recurso específico;
  • $format: permite definir o formato dos dados retornados em alguns tipos de consulta;
  • $filter: filtra um conjunto de resultados com base em determinadas condições, é igual a cláusula where do SQL;
  • $inlinecount – usado para paginação no lado do cliente. Ele informa a quantidade total de entidades buscadas do servidor para o cliente

Alguns exemplos:

Usando o operador $Select (aqui utilizando o Insomnia para fazer a requisição):

http://localhost:5000/Customer/GetData?$select=id,name
Solicitamos a nossa API que retorna-se no response somente as propriedades ID e NAME. Olha ae o ganho no peso do retorno!

Usando o operador $Filter no próprio browser (chrome):

http://localhost:5000/Customer/GetData?$select=id,name&$Filter=Name eq 'Wendy Waller'
consulta utilizando o $Filter.

Usando o operador $orderBy:

http://localhost:5000/Customer/GetData?$select=id,name&$orderBy=Name desc
consulta utilizando o $orderby

Usando o operador $top:

http://localhost:5000/Customer/GetData?$select=id,name&$top=2
consulta utilizando o $top

Para entender mais sobre OData recomendo esse vídeo da Microsoft.

Para este primeiro artigo, acho que já é bastante informação, vou criar outro com integração com o Entity Framework onde poderemos ver mais funcionalidades do OData em ação, aguardem.

Por enquanto é isso, como sempre se puder deixar a opinião sobre o artigo, ajuda a melhorar e dar continuidade no trabalho!

Abraço e até a próxima!


Deixe um comentário

O seu endereço de e-mail não será publicado.