GraphQL: a linguagem do Facebook para APIs
Neste artigo veremos uma introdução ao GraphQL, que é uma alternativa à maneira tradicional que conhecemos como REST, de se construir aplicações tipo API (Application Programming Interface).
As aplicações tipo API permitem que softwares externos acessem dados e serviços desta mesma aplicação através de endereços (“end-points”).
O que vamos aprender?
Vamos apresentar como pode ser feita essa integração do GraphQL em uma aplicação simples em Ruby On Rails, com resultados rápidos.
Se vocês precisam ou querem sair do tradicional e implementar APIs modernas com Ruby On Rails, então GraphQL pode ajudar nesse contexto.
Sigam o passo a passo e construam a aplicação na seção “Passo a Passo da criação do APP”. Assim, os conceitos, como o padrão de arquitetura do GraphQL, a integração com Rails e alguns outros detalhes podem ficar mais claros.
Espero que este material seja útil e ajude a criar uma aplicação tipo API com GraphQL 😉
Aproveitem o material e deixem uma mensagem. 😊… bóra ler o post 🚌
O que é o GraphQL?
GraphQL, como diz seu próprio site oficial é uma linguagem de consulta para APIs projetada pelos engenheiros do Facebook, criadores da famosa rede social de mesmo nome.
Aqui vale mencionar Lee Byron, um dos desenvolvedores que teve um papel importante na criação desta ferramenta.
Além de ser uma linguagem de consulta para APIs, GraphQL também é acompanhado de um mecanismo de execução de consulta de dados chamado de GraphiQL.
O GraphiQL é um recurso, feito em React, que oferece uma interface no browser para exibição da documentação para criação e testes de consultas das APIs que desenvolvemos usando GraphQL.
Ou seja, as consultas e operações que criamos usando GraphQL são instantaneamente disponibilizadas na documentação do GraphiQL e também usamos o próprio GraphiQL para testar essas consultas e operações da nossa aplicação API.
Mas por que esse nome?
GraphQL é uma especificação de API baseada em grafos.
A figura ao lado é um grafo, com vários pontos, chamados de nó e ligados uns aos outros.
Cada nó pode ser entendido como um recurso do sistema.
Um recurso pode ser um usuário, um cliente, uma pessoa e outro recurso pode ser o país do usuário, a peça fornecida pelo fornecedor, e assim por diante.
Dessa forma, o GraphQL permite a ligação entre recursos do sistema em forma de um grafo.
As letras “Q” e “L” da palavra GraphQL, significam “Query”, de consulta e “Language” de linguagem, respectivamente.
Portanto numa tradução livre podemos entender GraphQL como “linguagem de consulta de grafos”. \o/
Que problema o GraphQL resolve?
Criada pela equipe do Facebook em 2012, GraphQL começou a ser usada nos aplicativos desta empresa, e em 2015, esta solução foi disponibilizada como open source.
Segundo Lee Byron, falamos dele anteriormente neste artigo, o problema que eles enfrentaram e que serviu de motivação para criar esta solução, era obter os dados necessários para o feed de notícias do Facebook em dispositivos móveis, usando conexões de rede lentas.
Naquela época, esta foi uma questão extremamente importante para o Facebook. E a situação se complicava diariamente pois eram crescentes os acessos ao Facebook via dispositivos móveis.
O que vamos criar?
Vamos criar uma aplicação simples com dados de usuários e países, chamada GraphQLApp, baseada na gem GraphQL e na gem GraphiQL.
Para explorar alguns conceitos, vamos manipular nossa aplicação GraphQLApp, com customizações bem simples e mostrar o GraphQL em funcionamento, bem como fazer consultas no browser, pelo GraphiQL.
Ferramentas
- Ruby -> 2.5.0
- Ruby On Rails -> 5.1.4
- Gem GraphQL
- Gem GraphiQL
Não perca nenhum conteúdo
Receba nosso resumo semanal com os novos posts, cursos, talks e vagas o/
Passo a Passo da criação do APP GraphQLApp
I – Instalação
01) Para iniciar o nosso projeto, vamos criar uma pasta e entrar dentro dela.
|
1 2 |
$ mkdir graphqlapp $ cd graphqlapp |
02) Execute este passo somente se você usa o gerenciador de versões Ruby, RVM:
|
1 2 |
$ rvm use ruby-2.5.0@graphqlapp --ruby-version --create $ gem install rails -v 5.1.4 --no-ri --no-rdoc |
03) Agora vamos efetivamente criar nossa aplicação.
Vamos criar uma aplicação Rails com a opção “–api”, que não é obrigatório para o GraphQL, mas com “–api” estamos indicando que será uma aplicação somente backend e própria para APIs.
|
1 |
$ rails _5.1.4_ new . --api -T |
04) No arquivo Gemfile, inclua as gems:
|
1 2 3 4 |
gem 'graphql', '~> 1.7.13’ gem 'graphiql-rails', '~> 1.4.10', group: :development ## fornece uma interface de ## consulta via browser para ## GraphQL. |
05) Agora instale os módulos do GraphQL na aplicação, com o comando:
|
1 |
$ bundle install |
06) E agora o comando para criar o banco:
|
1 |
$ bundle exec rails db:create |
07) Continuando a instalação, vamos rodar um gerador que vem com a gem graphql, para gerar pastas, arquivos e configurações próprias desta gem.
|
1 |
$ bundle exec rails generate graphql:install |
Após o comando anterior, foi criada a pasta app/graphql/ com subpastas e arquivos do GraphQL.
Em app/controllers/, agora existe o arquivo graphql_controller.rb
08) Vamos editar o arquivo config/routes.rb.
Este arquivo agora deve ter o end-point do GraphQL:
|
1 |
post "/graphql", to: "graphql#execute" |
Mas vamos acrescentar mais uma linha que dará acesso ao GraphiQL.
E vamos dizer ao Rails para permitir que essa interface GraphiQL seja acessada somente em ambiente de desenvolvimento.
Em config/routes.rb, copie e cole:
|
1 |
mount GraphiQL::Rails::Engine, at: "/gq", graphql_path: "/graphql" if Rails.env.development? |
09) Mais um item para o GraphiQL rodar corretamente.
Em config/application.rb, retire um comentário. O seguinte “require” deve ficar assim:
|
1 |
require "sprockets/railtie" |
10) Agora é o momento de saber se o GraphiQL está funcionando 😏 …. suba o servidor Rails e chame o endereço abaixo usando seu browser preferido.
|
1 |
$ rails server |
11) Visite no seu browser: dating in san diego caNote que na URL aparece o “gq”, que foi a identificação que escolhemos para chamar o GraphiQL, no passo 08.
Se as coisas estão funcionando, uma tela parecida com a tela a seguir será apresentada:
Perceba que ao lado direito da tela existe uma área chamada “Documentation Explorer”.
Em “Documentation Explorer” será mostrada, de forma instantânea, uma documentação de toda implementação que fizermos no GraphQL.
Experimente digitar e depois executar a seguinte pesquisa, no lado esquerda tela:
|
1 2 3 |
{ testField } |
A seguinte resposta deverá aparecer:
|
1 2 3 4 5 |
{ "data": { "testField": "Hello World!" } } |
Agora sim, temos uma aplicação pronta para começar a implementar recursos com o GraphQL e Ruby On Rails 🎉
II – Implementação
Nessa parte vamos desenvolver nossa aplicação. Vamos criar dois recursos, com tabelas, dados e implementar seus end-points.
Teremos usuários, e associados a eles sua nacionalidade representada por um país. Portanto teremos User e Country respectivamente.
Criando os Models e alimentado dados
01) Usando o gerador de Model, vamos criar Country e User:
|
1 2 |
$ rails generate model Country abbreviation name $ rails generate model User name email phone_number:integer country:references is_admin:boolean |
02) Rodar as migrations para criar as models e tabelas:
|
1 |
$ rails db:migrate |
03) Agora vem a criação de dados para trabalharmos com consulta pelo GraphQL. Entrem no console do Rails e acrescentem as informações:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 |
$ rails console Country.create abbreviation: 'BRA', name: 'BRAZIL' Country.create abbreviation: 'USA', name: 'UNITED STATES OF AMERICA' User.create name: 'Isaac', email: 'isaac@gmail.com', phone_number: 5556767, country: Country.first, is_admin: true User.create name: 'Stephen', email: 'stephen@yahoo.com', phone_number: 5558989, country: Country.second, is_admin: false User.create name: 'Albert', email: 'albert@outlook.com', phone_number: 5554545, country: Country.second, is_admin: false exit |
Muito bem! E agora? Como vamos expor esses dados para o front-end consumir?
Resolvers
Vamos criar, o que no GraphQL é conhecido como “resolvers”, para dar à nossa aplicação, a capacidade de expor dados para consulta para algum serviço de front-end.
Criando o type User
04) Em app/graphql/types/query_type.rb
Faça o arquivo “query_type.rb” ficar da seguinte forma:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 |
Types::QueryType = GraphQL::ObjectType.define do name "Query" # chamamos o field de "user" e ele terá um # namespace chamado "Types" que chamamos # de "UserType" e ficará em # app/graphql/types/user_type.rb field :user, Types::UserType do # passamos aqui o "id" do User como argumento de consulta # esse valor de "id" vem do front-end para o back-end argument :id, types.ID # o "id" tem um tipo especial chamado ID description "Identificação do Usuário" # aqui é o método chamado "resolve" que resgata # os dados de User do banco de dados resolve -> (obj, args, ctx) { User.where(id: args[:id]).first } end end |
Calma, ainda não vai funcionar! ✋
Definimos o “field” User, agora temos que dizer quais são os “types”, ou seja, os campos que esse “field” usa.
Criando o field User
05) Vamos criar um arquivo “user_type” na pasta “app/graphql/types/”:
Em app/graphql/types/user_type.rb,
faça o arquivo “user_type.rb” ficar da seguinte forma:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 |
Types::UserType = GraphQL::ObjectType.define do name "UserType" # É como o schema irá identificar essa type. # Nesta parte informamos quais campos serão visíveis # numa consulta field :id, types.ID field :name, types.String field :email, types.String field :phone_number, types.Int field :is_admin, types.Boolean, "Usuario administrador?" # Vamos expor, não o código do País, # mas todos dados do País que estão no relacionamento # “user.country” field :country do type Types::CountryType description "País associado a este usuário" resolve ->(user, args, context){ user.country } end end |
Criando o field Country
06) Vamos criar um arquivo “country_type” na pasta “app/graphql/types/”:
Em app/graphql/types/country_type.rb,
faça o arquivo “country_type.rb” ficar da seguinte forma:
|
1 2 3 4 5 6 7 8 |
Types::CountryType = GraphQL::ObjectType.define do name "CountryType" # É como o schema irá identificar essa type. # Campos que serão visíveis numa consulta field :id, types.ID field :abbreviation, types.String field :name, types.String end |
07) Execute o servidor Rails:
|
1 |
$ rails server |
08) Visite no seu browser: dating in san diego caPodemos fazer várias consultas. Segue apenas um exemplo:
Consulta de dados de usuário
|
1 2 3 4 5 6 |
{ user(id: 1) { name email } } |
Resultado
|
1 2 3 4 5 6 7 |
{ "data": { "user": { "name": "Isaac" } } } |
Mais um exemplo:
Consulta de dados de usuário
|
1 2 3 4 5 6 7 8 9 10 |
{ user(id: 3) { email is_admin phone_number country { name } } } |
Resultado
|
1 2 3 4 5 6 7 8 9 10 11 12 |
{ "data": { "user": { "email": "albert@outlook.com", "is_admin": false, "phone_number": 5554545, "country": { "name": "UNITED STATES OF AMERICA" } } } } |
Tentem vocês agora. Criem mais um método de consulta chamado “allUsers”, para retornar todos os dados.
Ficaria assim:
Consulta de dados de usuário
|
1 2 3 4 5 6 |
{ allUsers { name email } } |
Resultado
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 |
{ "data": { "allUsers": [ { "name": "Isaac", "email": "isaac@gmail.com" }, { "name": "Stephen", "email": "stephen@yahoo.com" }, { "name": "Albert", "email": "albert@outlook.com" } ] } } |
Mutations
No GraphQL existem também as “mutations”. Servem para dar à nossa aplicação, a capacidade de receber do front-end, dados para inclusão, alteração ou exclusão de dados.
Ou seja, as “mutations” são operações de mudança de dados no back-end, enquanto que os “resolvers” que vimos anteriormente, são operações apenas para consulta de dados.
Mostramos apenas a mutation de inclusão de dados, mas caso desejem, posteriormente é possível seguindo este exemplo, construir as mutations de alteração e exclusão de dados.
Criando uma mutation para inserir dados
09) Em app/graphql/types/mutation_type.rb
faça o arquivo “mutation_type.rb” ficar da seguinte forma:
|
1 2 3 4 5 |
Types::MutationType = GraphQL::ObjectType.define do name "Mutation" field :createUser, function: Mutations::CreateUser.new end |
10) Em app/graphql/mutations/ crie um novo arquivo chamado “create_user.rb”
Em app/graphql/mutations/create_user.rb
faça o arquivo “create_user.rb” ficar da seguinte forma:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
class Mutations::CreateUser < GraphQL::Function argument :id, types.ID argument :name, types.String argument :email, types.String argument :phone_number, types.Int argument :is_admin, types.Boolean argument :country_id, types.Int type Types::UserType # especificação do tipo de retorno def call(obj, args, context) User.create(args.to_h) end end |
11) Execute o servidor Rails:
|
1 |
$ rails server |
12) Visite no seu browser: http://localhost:3000/gq
Segue um exemplo inserindo dados:
Inserção de dados de usuário
|
1 2 3 4 5 6 |
mutation { createUser(name: "Thomas", email: "thomas@gmail.com", phone_number: 5555555, is_admin: true, country_id: 2) { id name } } |
Resultado
|
1 2 3 4 5 6 7 8 |
{ "data": { "createUser": { "id": "4", "name": "Thomas" } } } |
Vamos consultar o novo usuário?
Consulta de dados de usuário
|
1 2 3 4 5 6 7 8 9 10 |
{ user(id: 4) { email is_admin phone_number country { name } } } |
Resultado
|
1 2 3 4 5 6 7 8 9 10 11 12 |
{ "data": { "user": { "email": "thomas@gmail.com", "is_admin": true, "phone_number": 5555555, "country": { "name": "UNITED STATES OF AMERICA" } } } } |
Conclusão
Neste artigo, criamos uma aplicação tipo API em Ruby on Rails com a gem GraphQL, que proporciona maior flexibilidade na medida que permite ao front-end construir suas próprias consultas de dados provenientes do back-end.
Acompanhamos na prática a criação da solução, aplicando os recursos de consulta e mudança de dados utilizando os recursos do GraphQL.
Na parte teórica do artigo, ficamos sabendo o que são as gems GraphQL e GraphiQL, a maneira que elas trabalham, os benefícios que trazem e os problemas que vieram resolver com essa nova proposta para aplicações tipo API.
Você pode acessar o código desenvolvido nesse tutorial clicando aqui \o/
Espero que o artigo seja útil em algum momento, e espero que tenham gostado! 👍
Até o próximo post 😎
Não perca nenhum conteúdo
Receba nosso resumo semanal com os novos posts, cursos, talks e vagas o/
Primeira vez no OneBitCode? Curtiu esse conteúdo?
O OneBitCode tem muito mais para você!
O OneBitCode traz conteúdos de qualidade, e em português, sobre programação com foco em Ruby on Rails e também JavaScript.
Além disso, aqui sempre levamos à você conteúdos valiosos sobre a carreira de programação, dicas sobre currículos, portfólios, perfil profissional, soft skills, enfim, tudo o que você precisa saber para continuar evoluindo como Programador(a)!
Fique por dentro de todos os conteúdos o/
Nossas redes sociais:
📹 • https://youtube.com/Onebitcode [Live todas as terças-feiras às 19h)
💻 • https://linkedin.com/company/onebitcode
🙂 • https://facebook.com/onebitcode
📱 • https://instagram.com/one_bit_code
🐦 • https://twitter.com/onebitcode
Nossos cursos:
🥇 • Programador Full Stack Javascript em 8 Semanas
💎 • Curso Completo de Ruby
⚙ • Minicurso: API Rails 5 Completo
🐞 • Minicurso de Testes para Ruby on Rails com RSpec
Espero que curta nossos conteúdos e sempre que precisar de ajuda, fala com a gente!
Estamos aqui para você 🙂
Bem-vindo à família OneBitCode o/
Ontem, 06/04/2018, realizei uma palestra sobre esse assunto na empresa em que trabalho. Os slides da palestra podem ser acessados aqui:
Palestra: GraphQL – A Linguagem do Facebook para APIs
Onde ficaria a lógica da apliaçação? Por exemplo, filtrar por kind do current_user. e etc.
Seria direto nas mutations?
Olá cheesepaulo, para realizar filtro em consultas, a lógica do filtro fica dentro de um resolver, que é o método de uma query GraphQL.
As mutations são operações de mudança de dados.
Qualquer outra dúvida pode nos enviar 😉
Abraços
Parabéns Sergio Lima, muito bem explicado, e compassado!
Obrigado Jonatas. Sempre bom receber esses feedbacks 😉