Oi, habrozhiteli! Publicamos um livro sobre a linguagem de consulta GraphQL. Decidimos compartilhar a tradução do capítulo "Anatomia das consultas GraphQL"
Snowtooth é uma estação de esqui fictícia. Por uma questão de exemplos neste capítulo, fingiremos que essa é uma montanha real e trabalharemos lá. Veremos como a equipe da web do Snow Fang usa o GraphQL para fornecer informações em tempo real: informações sobre o status dos teleféricos e pistas de esqui. O Snow Fang Ski Patrol pode abrir e fechar elevadores e pistas de esqui diretamente do seu smartphone. Para seguir os exemplos deste capítulo, consulte a interface Snow Fang na plataforma GraphQL Playground (snowtooth.moonhighway.com/).
Você pode usar a operação de consulta para consultar dados da API. A consulta descreve os dados que você deseja receber do servidor GraphQL. Ao enviar uma solicitação, você solicita as unidades de dados por campo. Esses campos são exibidos no mesmo campo na resposta de dados JSON que você recebe do servidor. Por exemplo, se você enviar uma solicitação allLifts e solicitar os campos de nome e status, deverá obter uma resposta JSON contendo uma matriz de allLifts e as cadeias de nome e status de cada elevação, conforme mostrado aqui:
query { allLifts { name status } }
Tratamento de erros
Pedidos bem-sucedidos retornam um documento JSON contendo a chave de dados. Solicitações com falha retornam um documento JSON contendo a chave de erro. Detalhes do que deu errado são transmitidos como dados JSON nessa chave. Uma resposta JSON pode conter "dados" e "erros".
Você pode adicionar várias consultas a um documento de consulta, mas apenas uma operação pode ser iniciada por vez. Por exemplo, você pode colocar duas operações de consulta em um documento de consulta:
query lifts { allLifts { name status } } query trails { allTrails { name difficulty } }
Quando você clica no botão play, o GraphQL Playground solicita que você selecione uma dessas duas operações.
Se você quiser enviar uma solicitação para todos os dados especificados, precisará colocar tudo na mesma solicitação:
query liftsAndTrails { liftCount(status: OPEN) allLifts { name status } allTrails { name difficulty } }
Aqui estão os benefícios do GraphQL. Podemos receber diferentes tipos de dados em uma solicitação. Solicitamos um liftCount por status, o que nos permite descobrir o número de elevadores que atualmente têm esse status. Também solicitamos o nome e o status de cada elevador. Por fim, solicitamos o nome e o status de cada rastreamento.
query é um tipo de GraphQL. Chamamos isso de tipo raiz, porque é o tipo que mapeia a operação, e as operações são as raízes do nosso documento de consulta. Os campos disponíveis para consulta na API do GraphQL são definidos neste esquema da API. A documentação indica quais campos estão disponíveis para seleção no tipo de consulta.
A documentação nos diz que podemos selecionar os campos liftCount, allLifts e allTrails ao chamar essa API. Ele também define mais campos disponíveis para seleção, mas o ponto principal da solicitação é que podemos escolher quais campos precisamos e quais omitir.
Quando escrevemos consultas, selecionamos os campos que precisamos, colocando-os entre chaves. Esses blocos são chamados de amostras. Os campos que definimos na seleção estão diretamente relacionados aos tipos de GraphQL. Os campos liftCount, allLifts e allTrails são definidos no tipo de consulta.
Você pode incorporar muitas seleções uma na outra. Como o campo allLifts retorna uma lista de elevadores, precisamos usar chaves para criar uma nova seleção para esse tipo. Existem todos os tipos de dados que podemos solicitar sobre o elevador, mas neste exemplo, precisamos apenas do nome e status do elevador. Da mesma forma, uma solicitação allTrails retornará tipos de trilhas.
A resposta JSON contém todos os dados que solicitamos. Esses dados são formatados como JSON e entregues da mesma forma que nossa solicitação. Cada campo JSON recebe o mesmo nome que o campo em nossa amostra. Podemos alterar os nomes dos campos no objeto de resposta na solicitação, especificando aliases, conforme mostrado abaixo:
query liftsAndTrails { open: liftCount(status: OPEN) chairlifts: allLifts { liftName: name status } skiSlopes: allTrails { name difficulty } }
A seguir está a resposta:
{ "data": { "open": 5, "chairlifts": [ { "liftName": "Astra Express", "status": "open" } ], "skiSlopes": [ { "name": "Ditch of Doom", "difficulty": "intermediate" } ] } }
Agora retornamos os dados da mesma forma, mas em nossa resposta renomeamos vários campos. Uma maneira de filtrar os resultados de uma consulta GraphQL é passar os argumentos da consulta. Argumentos são um par de valores-chave (ou pares) associados a um campo de solicitação. Se apenas os nomes dos elevadores fechados forem necessários, podemos enviar um argumento que filtrará nossa resposta:
query closedLifts { allLifts(status: "CLOSED" sortBy: "name") { name status } }
Você também pode usar argumentos para selecionar dados. Por exemplo, suponha que precisamos solicitar o status de um teleférico individual. Podemos escolher um elevador pelo seu identificador exclusivo:
query jazzCatStatus { Lift(id: "jazz-cat") { name status night elevationGain } }
Aqui vemos que a resposta contém nome, status, noite e elevação do ganho para o teleférico Jazz Cat.
»Mais informações sobre o livro podem ser encontradas no
site do editor»
Conteúdo»
TrechoCupom de 25% para
vendedores ambulantes -
GraphQLApós o pagamento da versão em papel do livro, uma versão eletrônica do livro é enviada por e-mail.