O que é OData?

OData (Open Data Protocolo) é um protocolo criado pela Microsoft para facilitar a criação e consumo de web services RESTful. Seu objetivo é definir padrões de como os serviços devem funcionar, a fim de permitir que os clientes os consumissem com facilidade, uma vez que estarão lidando com uma aplicação que segue uma padronização amplamente utilizada.

Por exemplo, esse protocolo define como deve ser a URL para realização de certas operações, como filtros e ordenação. Neste exemplo instalaremos um pacote via NuGet para implementar esses recursos de consulta seguindo o padrão OData.

Instalação do pacote

Neste exemplo partimos de um projeto ASP.NET Web API previamente criado e instalamos nele o pacote Microsoft.AspNet.WebApi.OData. Para isso utilizamos o NuGet e os passos executados são ilustrados na sequência de imagens abaixo:

Passo 1: Clicar com a direita em References / Manage Nuget Packages Passo 2: Pesquisar por OData e instalar o pacote Microsoft.AspNet.WebApi.OData Passo 3: Clicar em I Accept Final: Pacote instalado juntamente com suas dependências
#PraCegoVer - Transcrição dos Slides Passo 1: Clicar com a direita em References / Manage Nuget Packages
Passo 2: Pesquisar por OData e instalar o pacote Microsoft.AspNet.WebApi.OData
Passo 3: Clicar em I Accept na tela que se abrirá
Final: Pacote instalado juntamente com suas dependências

Habilitando as funcionalidades

Na sequência, para habilitar as operações de filtro, ordenação, etc. em nosso controller precisamos importar o seguinte namespace:

using System.Web.Http.OData;

Em seguida basta adicionar o atributo [EnableQuery] na action responsável pela listagem de registros:


  [EnableQuery]
  public IQueryable<Vaga> GetVagas()
  {
                  return db.Vagas;
  }

Aqui é importante destacar que o método que receber esse atributo deve retornar uma coleção do tipo IQueryable.

A partir de agora esse método já é capaz de tratar as operações de consulta do OData, que serão destacadas a seguir.

Operações do OData

Por padrão o método GetVagas é o responsável por tratar requisições GET na URL http:///api/vagas e retorna todos os objetos do tipo Vaga contidos no banco. A partir do momento que adicionamos a ele o atributo [EnableQuery] somos capazes de efetuar operações de consulta complexas passando alguns parâmetros:

  • /api/vagas?$filter=filtro: aplica filtros diversos seguindo do protocolo OData. Na Tabela 1 temos alguns exemplos de filtro que podem ser aplicados.

    $filter=Propriedade eq Valor Registros cuja “Propriedade” seja igual a “Valor”.
    $filter=Propriedade gt Valor Registros cuja “Propriedade” seja maior que (greater than) “Valor”.
    $filter=Propriedade lt Valor Registros cuja “Propriedade” seja menor que (less than) “Valor”.
    $filter=substring(‘Valor’, Propriedade) Registros cuja “Propriedade” contenha o texto “Valor”.

    Tabela 1. Exemplos de Filtros

    A lista completa de operadores disponíveis pode ser encontrada na documentação oficial do OData.

  • /api/vagas?$orderby=propriedadades: ordena o resultado a partir de uma ou várias propriedades, de forma crescente ou decrescente. Na Tabela 2 temos exemplos de ordenação.

    $orderby=Salario Ordena pelo campo SalarioInicial de forma crescente.
    $orderby=Salario, Id desc Ordena pelo campo SalarioInicial de forma crescente e pelo campo Id de forma decrescente.

    Tabela 2. Exemplos de ordenação

  • /api/vagas?$select=propriedades: define quais campos devem ser retornados no registro. Essa opção é particularmente útil para aplicações clientes que não precisam listar todos os dados do resultado na requisição. Para isso, é possível escolher apenas os campos que são úteis em cada contexto. Abaixo temos um exemplo de uso desse parâmetro:

    $select=Titulo, Salario Lista apenas os campos Titulo e Salario.

Limitando as operações suportadas

Quando adicionamos o atributo [EnableQuery] no método ele passa a suportar todas as operações do OData. No entanto, nem sempre queremos liberar tantas opções para os clientes. Nesses cenários podemos limitar as operações suportadas.

Para isso, o primeiro passo é importar o seguinte namespace:

using System.Web.Http.OData.Query;

Em seguida, basta especificar o argumento AllowedQueryOptions no atributo:


  [EnableQuery(AllowedQueryOptions = AllowedQueryOptions.Filter |
                                   AllowedQueryOptions.OrderBy |
                                    AllowedQueryOptions.Select)]
  public IQueryable<Vaga> GetVagas()
  {
         return db.Vagas;
  }

Agora apenas as operações de filtro, ordenação e seleção serão suportadas.

Sugestão de conteúdo

Para ver um web service completo em que utilizamos o OData para realizar consultas, confira o exemplo abaixo:

Web service RESTful com CRUD, filtros e ordenação usando ASP.NET Web API