¶ Introdução
GraphQL é uma linguagem desenvolvida para APIs de consulta, embora também possa ser utilizada para modificação de dados. A linguagem GraphQL permite que o desenvolvedor descreva detalhadamente quais dados ele deseja obter.
Quando comparada com o modelo REST, a API GraphQL possui a vantagem de ser mais dinâmica, tornando a evolução da API mais fácil, diferente do modelo REST, que precisa ter cada endpoint desenvolvido individualmente.
De forma análoga as APIs REST convencionais, a API GraphQL também é acessada através do protocolo HTTP.
Abaixo está um exemplo de consulta GraphQL na API Hubsoft. Veja que é possível especificar parâmetros de paginação, como ‘‘page’’ e ‘‘first’’, sendo ‘‘page’’ o número da página, e ‘‘first’’ a quantidade de itens por página. Além disso, é possível indicar também que se deseja obter os detalhes da paginação, tais como: número total de itens, página atual e última página. Por fim é possível especificar quais dados são desejados, através do atributo ‘‘data’’:
query Teste {
clientes(page: 1, first: 5) {
paginatorInfo {
currentPage
lastPage
total
}
data {
id_cliente
codigo_cliente
nome_razaosocial
cpf_cnpj
}
}
}
Essa query pode ser disparada utilizando-se o método POST do protocolo HTTP. O endpoint atual para consultas GraphQL é o /graphql/v1. Abaixo é possível visualizar um exemplo de resposta para a query em questão:
{
"data": {
"clientes": {
"paginatorInfo": {
"currentPage": 1,
"lastPage": 434,
"total": 2168
},
"data": [
{
"id_cliente": "10831",
"codigo_cliente": 51,
"nome_razaosocial": "ALINE MIRANDA SANTOS",
"cpf_cnpj": "XXXXXXXXX42"
},
{
"id_cliente": "24024",
"codigo_cliente": 1475,
"nome_razaosocial": "KARINA PALERMO PIRES",
"cpf_cnpj": "XXXXXXXXX70"
},
{
"id_cliente": "24121",
"codigo_cliente": 1535,
"nome_razaosocial": "NATALIA BORGES DA SILVA",
"cpf_cnpj": "XXXXXXXXX33"
},
{
"id_cliente": "25184",
"codigo_cliente": 2047,
"nome_razaosocial": "TESTE MARCOS",
"cpf_cnpj": "XXXXXXXXX08"
},
{
"id_cliente": "25087",
"codigo_cliente": 2002,
"nome_razaosocial": "VALERIO DE AGUIAR ZORZATO",
"cpf_cnpj": "XXXXXXXXX76"
}
]
}
}
}
¶ Autenticação na API GraphQL
A autenticação da API GraphQL é a mesma da API pública do Hubsoft, baseada no mecanismo OAuth. Para mais detalhes, acesse a documentação da API Oficial (API Oficial Hubsoft).
Um detalhe importante para a utilização da API, é que o usuário utilizado na autenticação permite estar liberado no Hubsoft para utilizar a API GraphQL. O acesso pode ser liberado ativando a chave destacada na imagem abaixo:
¶ Explorando o schema GraphQL no Postman
Algumas ferramentas de teste de APIs, como o Postman, já possuem suporte para interagir de forma mais intuitiva com APIs GraphQL. Através dessas ferramentas é possível visualizar o schema da API, que nada mais é que mapa da API, o qual descreve quais dados estão disponíveis para consulta, os parâmetros de filtros, etc.
- O primeiro passo é criar uma nova requisição, do tipo GraphQL
- Após criar a requisição, é necessário configurar a URL da API e o header de autenticação com o token OAuth.
- Ao mudar para a aba ‘‘Query’’, basta clicar no botão refresh para que o Postman sincronize o schema GraphQL
- Com o schema sincronizado, o processo de construção de queries fica muito mais simples, bastando clicar nos dados desejados e preencher os parâmetros de filtros
¶ Consultas de dados com faixas de data
Várias consultas na API GraphQL do Hubsoft possuem suporte à intervalo de datas, para utilizar essas consultas, basta preencher os parâmetros abaixo:
- de: Data inicial do intervalo
- ate: Data final do intervalo
A figura abaixo exemplifica uma consulta que utiliza tais parâmetros:
¶ Ordenação de resultados
Vários itens na consulta GraphQL suportam ordenação dos dados. Neste caso, é possível utilizar o parâmetro ‘‘orderBy’’ nas consultas, conforme ilustra a imagem abaixo:
¶ Considerações sobre performance
Apesar dos cuidados para que as consultas sejam otimizadas, é recomendado que não sejam feitas consultas pesadas de formas repetidas em pequenos intervalos de tempo. O ideal é se utilizar algum mecanismo de cache para tais consultas.