GraphQL API
Uma introdução às alternativas do futuro
Resumo
Com este ensaio teórico, faço uma primeira abordagem ao GraphQL, uma tecnologia poderosa e inovadora para a elaboração de API’s e que pode ser vista como uma boa e forte alternativa às API’s de REST.
Introdução
No mundo das API ‘s até relativamente à pouco tempo, a sua construção passava por uma arquitetura RESTful completa. Na atualidade, existem outras alternativas para a criação de API ’s. Uma tecnologia conceito muito buscada hoje em dia é o GraphQL. Criada pelo Facebook em 2012 e lançada em 2015 para o público.
É também bastante utilizada por várias empresas em plataformas muito conhecidas como o twitter, o pinterest, o github e claro o facebook.
GraphQL
Tal como o SQL é pensado como uma linguagem de consulta e manipulação das bases de dados relacionais, o GraphQL é também uma query language, no entanto, esta é utilizada para ler e alterar a informação de uma API que pode ser empregue nos nossos projetos, aplicações ou plataformas. Em si, é basicamente um conceito de linguagem, uma sintaxe, uma especificação para uma query language que apenas dita a forma da estrutura, a forma de como se deve parecer e funcionar / trabalhar.
GraphQL pode também ser dividido em duas componentes: a componente do lado do servidor (back end) e a componente do lado do cliente (front end).
Apesar do GraphQL ter uma relação muito próxima ao javascript, pelo motivo de que para o seu uso mais comum serem utilizadas ferramentas de javascript, principalmente o node.js, o GraphQL pode ser utilizado com múltiplas linguagens de programação tanto a nível do servidor como do lado do cliente, como já tinha referido antes.
Então, para usar GraphQL, seria preciso utilizar alguma aplicação para implementação da tecnologia, ou seja, para uma possível implementação seria necessário recorrer a serviços que disponibilizam esta criação de querys com base em GraphQL, como frameworks ou bibliotecas.
Muito resumidamente, estas são algumas das opções na comunidade:
Relativamente a server side podem ser utilizadas:
GraphQL.js | Apollo Server | Express GraphQL | graphql-yoga | GraphQL Helix
Relativamente a client side podem ser utilizadas:
Apollo Client | AWS Amplify | Relay | GraphQL Request | urql | graphql-hooks etc…
Na prática
Quando falamos sobre a sintaxe do GraphQL devemos olhar primeiramente para alguns conceitos iniciais como: schemas, types, fields e relationships.
Schemas
Os schemas são basicamente, toda a estrutura de uma API de graphQL. Desta forma, definir um schema não é mais do que definir todo um conjunto elementos necessários, como “types”, que estarão presentes dentro desta estrutura. O culminar de toda uma API numa espécie de planta de projeto. A sintaxe utilizada para a escrita destes schemas é chamada de (SDL) Schema Definition Language.
Types
Dentro de um schema, podemos encontrar vários tipos de types: Scalar Types, Object Types, Query Types, Mutation Types e Input Types. Estes servem para definir o tipo de dados possíveis dentro do schema.
- Scalar Types são relativos a um tipo de dados mais concreto como (INT), (Float), (String), (Boolean), (ID - conhecido por ser único e do tipo string generalizado);
- Object Types já são bem diferentes pois estes possuem um conjunto de fields (campos / atributos) onde dentro destes fields podemos encontrar Scalar Types ou outros Object Types também. Os Object Types encontrados num field fazem correspondência à origem desse Object Type;
O Object type Author, em si, também possui os seus próprios fields e types dentro de si;
- Query Types são operações de leitura que podem ser executadas pelo cliente de forma a obter uma informação diretamente de uma API;
- Mutation Types são operações que permitem realizar manipulações na própria API;
- Input Types são operações que permitem a inserção de dados na API;
Os pontos de exclamação ( ! ) servem para identificar quando um field não pode ser nulo / vazio.
Relationships
Em GraphQL também podem ser criadas relações entre os vários Object Types presentes no schema.
Levando a imagem abaixo como exemplo, podemos ver que o Object Type Book tem dentro, como field author, um outro Object Type que é Author. À direita, o Object Type Author tem dentro, como field books, um Object Type book. Desta forma e observando que cada um dos Object Types têm o outro a ser chamado dentro de si, podemos concluir que existe uma relação entre eles.
No caso esta relação seria um para muitos, pois em Book apenas é chamado um valor de Author enquanto dentro de Author está a ser chamado um array de [Book] com vários resultados, significando que, um livro pode pertencer a um autor enquanto um autor pode ter vários livros.
Queries
Como disse anteriormente, as queries são basicamente estas pequenas operações de pesquisa / leitura de uma API que acontecem do lado do cliente. Em comparação às API’s de REST, as consultas de GraphQL apenas devolvem ao cliente a exata informação que ele pediu, facilitando e otimizando as pesquisas feitas ao servidor.
Neste exemplo de uma hipotética query, o field de “utilizadores” é chamado de root field e tudo que vem dentro dele é o payload.
No caso, dentro do payload, apenas temos “nomes”, o que quer dizer que a query apenas vai buscar pelos nomes dos utilizadores no servidor.
Da mesma forma, irão aparecer, apenas, todos os “nomes” que estiverem presentes no servidor.
Na imagem ao lado podemos observar o resultado: Tiago, Sara e Marco.
Todo este processo entra na filosofia direta do GraphQL que acaba por descrever isto da seguinte forma:
“ask for what you need and you’ll get exactly that”.
Se quisermos adicionar mais fields no payload, simplesmente, iremos obter mais campos de resultados associados diretamente aos utilizadores. Desta forma, cada pesquisa torna-se única e adaptável a cada momento de necessidade.
Se quisermos impor alguma restrição à pesquisa, podemos sempre usar argumentos. Pequenas condições.
Neste exemplo, o field “nomes” tem de ser “Marco”
O resultado desta query seria algo simples na imagem ao lado:
Por último, numa consulta também é possível passar argumentos através de variáveis. As variáveis são expressas tal como em php, ou seja, utilizando ($). Para as utilizar num argumento basta chamá-las. Ex:
Desta forma é possível tornar os argumentos mais dinâmicos.
Mutations
As mutations são uma das principais operações em GraphQL. Com as mutations é possível criar, atualizar e apagar informações de uma API de graphQL.
A sintaxe usada para as mutations ébasicamente a mesmas que para as queries com uma pequena diferença. Para mutations a keyword utilizada deve ser a própria palavra mutations.
Subscriptions
Através das subscriptions o cliente poderá manter uma ligação em tempo real com o servidor. Desta forma, sempre que aconteça alguma inserção de dados no servidor o utilizador poderá receber uma notificação com o novo conteúdo disponível.
Estes “updates” de informação apenas iram acontecer se houver uma subscription por parte do cliente para um determinado ponto de informação presente no servidor.
As principais vantagens do GraphQL face ao REST
- O URL do REST acaba por ficar bastante mais comprido e mais complexa em relação ao GraphQL;
- No REST acontece o Over-fetching. Isto é, quando o resultado de devolver dados é maior do que os que foram pedidos e o under-fetching quando não recebemos os dados suficientes e precisamos realizar mais chamadas da informação de forma a conseguir os dados que precisamos.
- O REST acaba por realizar muito mais requisições HTTP quando a sua estrutura de dados é um pouco mais complexa.
Conclusões
Para terminar e resumir o GraphQL, percebemos que é uma tecnologia, com uma sintaxe relativamente simples, criada para facilitar bem mais o trabalho do programador na hora de desenvolver uma API. Ao longo deste ensaio, conseguimos compreender os conceitos básicos e primários da sua escrita e manipulação.
