Sobre GraphQL

Por que usamos GraphQL

O uso do modelo de chamadas via GraphQL foi escolhido por ser uma tecnologia moderna que oferece apenas um ponto de acesso ao serviço oferecido e facilita a quantidade de informações requisitadas pelo cliente.

No modelo REST, o cliente precisaria requisitar diversas vezes para obter todas as informações referentes a uma apólice, como por exemplo, os dados básicos da apólice, dados de sinistros associados, assistências.

No modelo GraphQL, o cliente pode requisitar todas as informações numa única requisição. Assim ele evita ter múltiplas conexões ao servidor. Também permite escolher quais atributos são desejados receber, diferente do modelo REST que retorna todos os atributos.

O modelo de GraphQL também trabalha com erros e status identificado dentro do retorno da operação. Permitindo que os erros sejam verificados seguindo uma estrutura já esperada.

Como funciona as requisições com GraphQL

As requisições feitas por GraphQL seguem uma estrutura de linguagem simples, onde indicamos na consulta a operação ou filtro, quais atributos serão fornecidos para a operação/filtro e os campos desejados em receber.

No exemplo abaixo a consulta realiza o filtro de apólices trazendo apenas alguns dados básicos

query {
  policies(orderBy: { createdAt: ASC}) {
    nodes {
      number
      createdAt
    }
  }
}

É possível trazer mais dados na mesma requisição

query {
  policies(orderBy: { createdAt: ASC}) {
    nodes {
      number
      createdAt
      coverages {
        description
        deductible
      }
      assistances {
        description
        name
      }
    }
  }
}

Também é possível realizar duas ou mais consultas numa mesma requisição, onde na consulta abaixo na mesma requisição será retornado uma listagem de cotações e uma listagem de ocupações

query {
  orders(orderBy: { createdAt: DESC }) {
    nodes {
      createdAt
      product
      insuredPerson {
        name
      }
    }
  }
  occupations {
    code
    name
  }
}

Nas operações acima, foram realizadas apenas consultas, mas o GraphQL também permite operações de alteração, criação e remoção. Essas operações são conhecidas como mutation. Abaixo um exemplo para criar uma cotação de produto AUTO.

mutation {
  createAutoOrder(
    input: {
      attributes: {
        driver: {
          youngDriverCoverage: false,
          name: "John Youser",
          gender: MALE,
          maritalStatus: MARRIED,
          dateOfBirth: "1980-01-01",
          document: {
              type: CPF,
              number: "123.456.700-88"
          }
        },
        insuredPerson: {
          name: "John Youser",
          gender: MALE,
          maritalStatus: MARRIED,
          phone: "(11) 99999-9999",
          dateOfBirth: "1980-01-01",
          address: {
            number: "68",
            zipCode: "04552-040"
          },
          salaryRange: BAND4,
          nationality: BR,
          document: {
            type: CPF,
            number: "123.456.700-88"
          },
          email: "cenario-parceiro@youse.com.br"
        },
        createdFromIp: "192.168.1.1",
        userAgent: "chrome",
        vehicle: {
          adaptedWithGasKit: false,
          year: 2008,
          adaptedForDisabilities: false,
          fuelType: "gasoline",
          address: {
            zipCode: "04552-040"
          },
          licensePlate: "YOU-0000",
          usage: ONLY_PRIVATE,
          bulletProof: false,
          ownershipStatus: OWNED_BY_PERSON,
          brandNew: false,
        }
      }
    }
  ) {
    id
    success
    order {
      createdAt
      id
      errors {
        attribute
        messages {
          code
          description
        }
      }
      coverages {
        name
      }
      vehicle {
        errors {
          attribute
          messages {
            code
            description
          }
        }
      }
    }
  }
}

Observando na “mutation” acima, temos a operação createAutoOrder onde dentro dos parentes “()” são passados os atributos e depois os atributos esperados da criação da cotação.

Diversas consultas e operações são fornecidas, a documentação abaixo apresenta as ações disponíveis, suas entradas e saídas.

Algumas ferramentas facilitam a criação das consultas e mutações, como o POSTMAN, o Altair GraphQL

E para cada linguagem também existem bibliotecas que facilitam as operações, veja em: https://graphql.org/code/