Pensando no design de uma api GraphQL
Este artigo é o pontapé inicial de uma sequência de artigos sobre GraphQL. A intenção desta série é explicar e exemplificar conceitos básicos sobre GraphQL, em português e da forma mais objetiva possível.
Schema first (esquema primeiro)
É Uma metodologia de design que tem como objetivo definir os tipos de dados que a sua API lidará, antes mesmo de começar a sua produção.
Esse conjunto de tipos é chamado de Schema (esquema).
Um tipo representa um objeto personalizado que possui campos (propriedades) que representam os dados associados a cada objeto. Cada campo retorna um tipo de dado.
Neste artigo, desenvolveremos o schema de uma API de biblioteca virtual. O schema terá dois tipos principais: Book e Author.
Vamos começar definindo o tipo Book:
- id: define um identificador único para cada livro.
- !ID: o tipo escalar ID retorna um identificador único para cada livro. O “!” define que o ID não pode ser nulo (not null).
- name: string, obrigatório
- synopsis: string, não obrigatório.
Podemos adicionar a data de publicação do livro ao tipo Book, através da criação de um tipo escalar.
Faz sentido adicionar o gênero do livro ao tipo Book. Podemos representar o gênero do livro através de um tipo enumerado (enum). Os tipos enumerados possibilitam que um campo retorne um conjunto de opções.
Criando o tipo enum chamado BookGenre:
Agora, vamos adicionar um campo genre ao nosso tipo objeto Book:
Dessa forma, garantimos que genre devolverá um dos sete valores contidos no tipo enumerado que foi implementado.
Listas
É possível definir campos que retornem listas de qualquer tipo em um schema GraphQL. Basta utilizar o nome do campo entre [ ]. Por exemplo, [BookGenre] define uma lista de gêneros dos livros. Podemos utilizar as listas para conectar objetos uns aos outros.
Conectando os livros aos autores
Livros são escritos por autores, portanto todo livro deve estar conectado ao autor que o escreveu. Podemos definir a afirmação acima no schema da seguinte forma:
O tipo Author foi criado, contendo somente um identificador único e o campo name, do tipo String.
A conexão é inserida ao adicionar o campo writtenBy ao objeto Book. Este campo é definido com o tipo Author, que não pode ser nulo.
Conectando os autores aos livros.
Quando consultarmos um autor, devemos ser capazes de ver todos os livros que aquele autor escreveu:
O campo publishedBooks devolverá uma lista de tipos Book.
Para deixar nossos tipos Book e Author disponíveis para uma consulta, devemos definir os campos da nossa query, observe:
O tipo query definirá as consultas que estarão disponíveis na API. Adicionamos duas consultas para cada tipo, uma exibe o número total de registros e outra o conteúdo desses registros.
No próximo artigo, falaremos sobre argumentos em GraphQL, englobando filtragem, paginação e ordenação de dados. Também descobriremos o que são e definiremos mutations e subscriptions pro nosso schema.
Os seguintes links / livros foram usados como referência / base de conhecimento para a produção deste artigo:
- GraphQL Server Basics: GraphQL Schemas, TypeDefs & Resolvers Explained — https://www.prisma.io/blog/graphql-server-basics-the-schema-ac5e2950214e#9d03
- Schemas and Types, documentação oficial: https://graphql.org/learn/schema/
- PORCELLO, Eve; BANKS, Alex. Introdução ao GraphQL: Busca de dados com abordagem declarativa para aplicações web modernas. Novatec, 2018.
