Tutorial de uso das APIs de entidade com filtros OData

O OData, Open Data Protocol, é um protocolo aberto que permite a criação e consumo de APIs RESTful de maneira simples e padrão. As APIs de entidade na Senior, atualmente, utilizam apenas parte do Query Data. Mais especificamente, as opções filter e orderby.

Para consumir as APIs de entidade é necessário seguir os padrões:

• Método HTTP GET
• E URL https://api.senior.com.br/{dominio}/{serviço}/entities/{nomeDaEntidade}

Obs.: Caso a entidade exija autenticação, é necessário incluir no HTTP Header o “Authorization: Bearer {access-token}”. Para obter o access-token, favor consultar o Tutorial da API Authentication.

Opção Filter

Ao efetuar uma chamada para uma entidade, por padrão, são retornados todos os registros da entidade. Porém, com o OData, é possível restringir os registros retornados, utilizando o parâmetro filter. O exemplo abaixo retornará todos os registros da entidade visitType (tipos de visita), do domínio sam, serviço lobby, cujos ids sejam maior que 2 e menor que 5, ou seja, os registros com id igual a 3 e 4.

Abaixo é mostrada uma tabela contendo os operadores e funções suportados pela busca com filtro:

Operador	Descrição	Exemplo
eq	= (igual)	filter=id eq 10
ne	<> (diferente)	filter=id ne 10
lt	< (menor que)	filter=id lt 10
gt	> (maior que)	filter=id gt 10
le	<= (menor ou igual)	filter=id le 10
ge	>= (maior ou igual)	filter=id ge 10
is	Verifica se parâmetro é nulo	filter=id is null
containing	Contendo valor da direita no atributo da esquerda	filter=containing(name, 'albert')
lower	Função de caixa baixa	filter=containing(lower(name), lower('Albert'))
and	E	filter=id eq 10 and status eq 'y'
or	Ou	filter=id eq 10 or id eq 20

Observações

• Podem ser utilizados parênteses entre as expressões.
• Caso utilize alguma função (com exceção da função containing), o nome da função deve ser exatamente o mesmo nome da função suportada pelo banco de dados, como por exemplo lower.
• Dependendo da entidade e do atributo filtrado, o desempenho da consulta poderá ser afetado. Caso a consulta fique lenta, tente rever o formato de filtro utilizado.
• A função containing suporta apenas valores string no segundo parâmetro, o valor deve ser precedido e seguido por aspas simples.
• Com exceção da função containing, outras funções de banco de dados podem ser utilizadas, porém somente são suportados funções com apenas um parâmetro, exemplo: ?filter=lower(trim(customerName)) eq lower(trim(‘ marie curie ‘)) ou ?filter=trunc(total) ge round(2589.45).
• Caso existir aspas simples (apóstrofo) no meio da busca, deve-se colocar a contra barra, exemplo: ?filter=nome eq ‘Caixa d\’água’.
• São suportados até quatro níveis de entidades encadeadas para filtros. Ex.: ?filter=objNivel2.objNivel3.objNivel4.id eq ’93eab564-0d3c-4e1a-b2ab-5dc293e5deb5′.

Abaixo é apresentada uma tabela contento exemplos de filtros e os tipos de campos suportados:

Campo da entidade: tipo	Exemplo
stringField: string	filter=stringField eq 'this is a plane text'
booleanField: boolean	filter=booleanField eq true
integerField: integer	filter=integerField ge 12345
doubleField: double	filter=doubleField eq 5890.159
dateField: date	filter=dateField eq '2018-04-04'
timeField: time	filter=timeField eq '12:40:38'
dateTimeField: dateTime	filter=dateTimeField eq '2018-04-04T12:40:38.155Z'
moneyField: money	filter=moneyField gt 1234567890.098
enumField: fruit	filter=enumField eq APPLE
uuidField: uuid	filter=uuidField eq 'a9abe17c-ac41-43bf-9d35-52cb8034d486'
binaryField: binary	Não suportado

Opção Orderby

Com o orderby é possível definir a ordem em que os registros de uma entidade devem ser retornados. Pode ser feito com qualquer campo do retorno, até quatro níveis. E por padrão a ordenação é sempre em ordem crescente. Caso haja a necessidade de ordenar em ordem decrescente, basta adicionar um espaço em branco e o termo desc após o nome do atributo. Como demonstramos no exemplo abaixo, que retornará todos os registros de tipos de visita ordenados pelo nome em ordem decrescente:

Também é possível filtrar e efetuar a ordenação por mais de um campo, basta separá-los por vírgula:

Opções Adicionais

Essas opções são extras, não fazem parte do OData, mas que visam facilitar o desenvolvimento.

Size e Offset

Essas duas opções estão relacionadas a quantidade de registros por página (size) e o número da página a ser recuperada (offset), lembrando que a numeração de página começa em 0 (zero).

No exemplo abaixo temos um exemplo de consulta, para retornar 2 registros na página 1, ordenado pelo nome.

Displayfields

Com o displayfields é possível informar quais campos da entidade devem ser retornados pela API, visto que, por padrão, são retornados todos os campos da entidade (os relacionamentos não são retornados por padrão, apenas os atributos da própria entidade). Essa opção permite reduzir o tamanho da resposta. Para isso basta informar os campos separados por vírgula, conforme exemplo abaixo:

Para buscar os relacionamentos da entidade é necessário passar o relacionamento juntamente com os atibutos da entidade relacionada, conforme exemplo abaixo:

Caso seja utilizado o displayFields para buscar entidades relacionadas, apenas o atributo id da entidade será carregado por padrão. Para buscar as informações da entidade e mais as informações da entidade relacionada é possível utilizar o displayFields conforme o exemplo abaixo:

Dessa forma o * serve para carregar os atributos do vacancy (entidade) e o jobPosition.* serve para carregar os atributos do jobPosition (entidade relacionada com o vacancy)