Como realizar filtros e manipulações adicionais nas API's com oData

OData (Open Data Protocol) é um padrão internacional que facilita o consumo e manipulação de API's e pode ser utilizado em algumas API's do Zeev.

O que é oData?

OData (Open Data Protocol) é um padrão internacional que facilita o consumo e manipulação de API's. Com uso de comandos oData, você pode:

• Realizar filtros adicionais sobre os dados retornados por uma API;

• Limitar os campos retornados por uma API;

• Modificar a ordenação do retorno de uma API;

• Limitar o número de registros retornados de uma API;

Quando é possível utilizar oData

As API's do Zeev onde o uso de oData é permitido explicitamente indicarão isso em sua documentação nesse site. Nas API's onde não há referência de oData, não haverá suporte a esse recurso.

Se você tentar utilizar filtros oData em API's que não suportam isso, receberá erro 400 - BadRequest, similar ao abaixo:

{
	"error": {
		"code": "400",
		"key": "api.badrequest",
		"message": "The query specified in the URI is not valid. Query option 'Expand' is not allowed. To allow it, set the 'AllowedQueryOptions' property on EnableQueryAttribute or QueryValidationSettings.",
		"vars": null,
		"details": []
	}
}

Como filtrar retornos de API's com oData

Sempre prefira e utilize os métodos de filtro da própria API. Por exemplo, a API de Listar pessoaspossui, ela própria, propriedades de filtro pré-definidas para isActive. Utilize sempre os filtros, seja o documento JSON de filtro, sejam propriedades na URL de filtro, nativas da API.

Os filtros adicionais em OData permitem que os clientes restrinjam os resultados de uma consulta para incluir apenas os registros que atendem a critérios específicos. Esses filtros são aplicados usando a cláusula $filter na URL da requisição. A sintaxe do OData permite o uso de uma variedade de operadores de comparação e funções para criar filtros complexos.

Operadores de Comparação OData

OData suporta uma ampla gama de operadores de comparação que podem ser usados para criar filtros. Alguns dos operadores mais comuns incluem:

• eq: Igual a

• ne: Diferente de

• gt: Maior que

• ge: Maior ou igual a

• lt: Menor que

• le: Menor ou igual a

• and: E lógico

• or: Ou lógico

• not: Negação lógica

Exemplos de Uso

A seguir, apresentamos exemplos práticos de como usar filtros adicionais com OData em diferentes casos de uso.

Filtrando por Igualdade

Para filtrar dados que são iguais a um valor específico, usa-se o operador eq. Por exemplo, em uma API fictícia, para obter todos os clientes cujo país seja "Brasil" a partir da propriedade country:

GET /Customers?$filter=country eq 'Brasil'

Ou, no caso abaixo, para obter todos os clientes que estejam ativos a partir da propriedade isAtive:

GET /Customers?$filter=isActive eq true

Filtrando por Inequalidade

Para excluir dados que são iguais a um valor específico, usa-se o operador ne. Por exemplo, em uma API fictícia, para obter todos os clientes que não estão no país "Brasil" a partir da propriedade country:

GET /Customers?$filter=country ne 'Brasil'

Filtrando por Intervalos de Valores

Os operadores gt, ge, lt, e le são usados para filtrar dados dentro de intervalos de valores. Por exemplo, em uma API fictícia, para obter produtos cujo preço seja maior que 100 a partir da propriedade price:

GET /Products?$filter=price gt 100

Ou para obter produtos cujo preço esteja entre 50 e 150:

GET /Products?$filter=price ge 50 and price le 150

Filtrando por Campos de Texto

Para realizar filtros em campos de texto, podem ser usadas funções como substringof.

Por exemplo, em uma API fictícia, para obter todos os clientes cujo nome contém "Rafael" a partir da propriedade name:

GET /Customers?$filter=substringof('Rafael', name)

Aqui também pode ser utilizada a expressão contains, função essencial para verificar se uma string contém outra.

Outro reforço importante é o uso da expressão toupper, que torna as buscas como case-insensitive. Por exemplo, uma pesquisa case-insensitive para buscar os usuários que contém "dos Santos" a partir da propriedade name, dentro do campo do formulário "Nome":

GET /Users?$filter=contains(toupper(name), toupper('{Form.Nome}'))

Combinação de Filtros

Filtros podem ser combinados usando operadores lógicos como and e or. Por exemplo, em uma API fictícia, para obter produtos cujo preço seja menor que 50 ou cujo estoque seja maior que 200:

GET /Products?$filter=price lt 50 or stock gt 200

Filtrando por Datas

Para filtrar dados por datas, usa-se a função datetime. Por exemplo, em uma API fictícia, para obter pedidos feitos após 1º de janeiro de 2022 a partir da propriedade OrderDate:

GET /Orders?$filter=orderDate gt datetime'2022-01-01T00:00:00'

Como selecionar propriedades em retornos de API's com oData

O operador select permite que os clientes especifiquem uma lista de campos que devem ser incluídos na resposta da API. Isso é útil quando os clientes não precisam de todos os campos de uma entidade, mas apenas de um subconjunto específico. A cláusula $select é usada na URL da requisição para indicar os campos desejados.

Sintaxe do Operador select

A cláusula $select segue a seguinte estrutura:

$select=fieldName1,fieldName2,fieldName3

• fieldName1, fieldName2, fieldName3: Os nomes dos campos que se deseja incluir na resposta.

Exemplos de Uso

A seguir, apresentamos exemplos práticos de como usar o operador select com OData em diferentes casos de uso.

Seleção de Campos Específicos

Em uma API fictívia, para obter apenas os campos name e country de todos os clientes:

GET /Customers?$select=name,country

Como ordenar retornos de API's com oData

As operações de ordenação em OData permitem que os clientes especifiquem a ordem em que os resultados devem ser retornados. Isso é realizado usando a cláusula $orderby na URL da requisição. A sintaxe do OData permite a ordenação por um ou mais campos, tanto em ordem crescente quanto decrescente.

Sintaxe de Ordenação

A cláusula $orderby segue a seguinte estrutura:

$orderby=fieldName [asc|desc]

• fieldName: O nome do campo pelo qual deseja ordenar.

• asc: Ordem crescente (padrão).

• desc: Ordem decrescente.

Exemplos de Uso

A seguir, apresentamos exemplos práticos de como usar operações de ordenação com OData em diferentes casos de uso.

Ordenação por um Campo

Para ordenar dados por um único campo em ordem crescente, simplesmente especifique o nome do campo. Por exemplo, para obter todos os clientes ordenados pelo nome:

GET /Customers?$orderby=name

Para ordenar os clientes pelo nome em ordem decrescente:

GET /Customers?$orderby=name desc

Ordenação por Múltiplos Campos

É possível ordenar por múltiplos campos, separando-os por vírgulas. Por exemplo, para ordenar os clientes pelo país em ordem crescente e, dentro de cada país, pelo nome em ordem decrescente:

GET /Customers?$orderby=country, name desc

Como limitar o número de registros nos retornos de API's com oData

Essa propriedade não pode ser usada para tentar sobrescrever os limites de número de registros retornados em API's paginadas.

O operador $top permite que os clientes especifiquem o número máximo de registros a serem retornados na resposta de uma consulta, após os limites e filtros nativos já aplicados pela própria API.

Sintaxe do Operador $top

A cláusula $top segue a seguinte estrutura:

$top=N

• N: O número máximo de registros a serem retornados.

Exemplos de Uso

A seguir, apresentamos exemplos práticos de como usar o operador $top com OData em diferentes casos de uso.

Limitação de Resultados

Para obter apenas os 10 primeiros clientes:

GET /Customers?$top=10