GraphQL é uma linguagem de consulta para APIs e um ambiente de execução para preencher essas consultas com seus dados existentes.
Consultas (Queries)
Consulta básica e resposta JSON
{ status }
JSON Response:
{
"data": {
"status": "available"
}
}
Objetos aninhados
{
hero {
name
height
}
}
Listas
{
friends {
name
}
}
Argumentos
{
hero(id: "1000") {
id
name
}
}
Apelidos (Aliases)
{
luke: hero(id: "1000") {
name
}
han: hero(id: "1001") {
name
}
}
Nomes de operação e variáveis
Query Definition:
query FindHero($id: String!) {
hero(id: $id) {
name
}
}
Variables Payload (JSON):
{
"id": "1000"
}
Mutações (Mutations)
mutation CreateReviewForEpisode($ep: Episode!, $review: ReviewInput!) {
createReview(episode: $ep, review: $review) {
stars
commentary
}
}
Fragmentos em linha (Inline Fragments)
{
search(q: "john") {
id
... on User {
name
}
... on Comment {
body
author {
name
}
}
}
}
GraphQL via HTTP
Requisição GET
fetch('https://api.example.com/graphql?query={me{name}}')
Requisição POST
fetch('https://api.example.com/graphql', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
query: 'query GetHero($id: String!) { hero(id: $id) { name } }',
variables: { id: '1000' }
})
})
Linguagem de Definição de Esquema (SDL)
Tipos básicos
type Query {
me: User
users(limit: Int): [User]
}
type User {
id: ID!
name: String
}
Tipos escalares nativos
| Escalar | Descrição |
|---|---|
Int |
Inteiro de 32 bits com sinal |
Float |
Número de ponto flutuante com precisão dupla |
String |
Sequência de caracteres UTF-8 |
Boolean |
Valor booleano true ou false |
ID |
Identificador exclusivo serializado como string |
Palavras-chave de definição de tipos
| Palavra-chave | Descrição |
|---|---|
type |
Tipo de objeto representando um conjunto de campos |
scalar |
Tipo escalar primitivo personalizado |
interface |
Tipo abstrato que define campos obrigatórios a serem implementados |
union |
Tipo abstrato que agrupa vários tipos de objeto |
enum |
Enumeração de valores literais permitidos |
input |
Objeto complexo passado como argumento em operações |
Modificadores de tipo
| Modificador | Descrição |
|---|---|
String |
String que permite valor nulo (Nullable) |
String! |
String obrigatória não nula (Non-nullable) |
[String] |
Lista que permite nulo com strings que permitem nulo |
[String]! |
Lista obrigatória com strings que permitem nulo |
[String!]! |
Lista obrigatória com strings obrigatórias |
Interfaces
interface Entity {
id: ID!
}
type User implements Entity {
id: ID!
name: String
}
Enumerações (Enums)
enum Direction {
NORTH
EAST
SOUTH
WEST
}
Uniões (Unions)
union SearchResult = Human | Droid | Starship
type Query {
search(text: String): [SearchResult]
}