Backend & APIs Nathan Geeksman

API REST vs. GraphQL: Qual modelo de comunicação adotar?

API REST vs. GraphQL: Qual modelo de comunicação adotar?

API REST vs. GraphQL: Qual modelo de comunicação adotar?

Introdução

A arquitetura de software está cada vez mais focada na entrega de serviços de forma escalável e segura, sendo a API REST um dos modelos de comunicação mais utilizados nos últimos anos. No entanto, o GraphQL vem ganhando espaço como alternativa viável para abordar desafios específicos presentes no desenvolvimento de software, especialmente em sistemas complexos que lidam com grandes volumes de dados e requisições variadas.

O objetivo desse artigo é apresentar uma visão comparativa entre as duas opções mais populares atuais: API REST e GraphQL. Com base na análise dos principais aspectos técnicos, objetivos de design e considerações práticas de implementação, será possível identificar pontos fortes e fracos de cada abordagem, ajudando os desenvolvedores a decidir qual modelo de comunicação melhor se adequa às necessidades do seu projeto. Ao final da leitura, o leitor terá uma compreensão clara sobre como escolher entre API REST e GraphQL para garantir a eficiência e escalabilidade em seus sistemas de software.

O que é e por que importa

API REST (Application Programming Interface Representational State of Resource) é um padrão de arquitetura para construir sistemas distribuídos, definido em 2000 pelo profissional Roy Fielding. Esse modelo adota princípios como a restrição do estado na camada de apresentação e o uso de recursos identificados por URIs.

Por outro lado, GraphQL é uma linguagem de query que permite aos usuários da API especificarem exatamente os dados necessários para cada solicitação. O desenvolvedor define um schema, onde são definidas as entidades e campos disponíveis em sua API. Ao fazer a requisição, o cliente fornece uma query, descrevendo quais entidades e campos ele precisa acessar.

API REST é amplamente adotado devido à facilidade de implementação e entendimento por parte dos desenvolvedores. No entanto, o modelo tem alguns limites em termos de flexibilidade na requisição de dados específicos. Já GraphQL oferece uma maior flexibilidade e desempenho, pois os clientes podem solicitar apenas as informações necessárias, reduzindo o tamanho da resposta e otimizando a comunicação.

A escolha entre essas opções dependerá das necessidades específicas do seu sistema de software. Se você trabalhar com sistemas simples ou que lidam com pequenos volumes de dados, a API REST pode ser uma escolha adequada. Por outro lado, em sistemas complexos que exigem alta flexibilidade e escalabilidade, o GraphQL é mais indicado.

Essa seção visa fornecer aos leitores uma compreensão básica sobre as tecnologias em questão, ajudando a contextualizar os pontos fortes e fracos de cada abordagem ao longo do artigo.

Como funciona na prática

API REST

A comunicação por meio de APIs REST ocorre de acordo com as seguintes etapas:

  • O cliente envia uma solicitação HTTP (GET, POST, PUT, DELETE) para a URI correspondente ao recurso solicitado.
  • O servidor recebe a solicitação e processa a requisição de acordo com o método HTTP utilizado.
  • Caso necessário, o servidor busca dados relacionados no banco de dados ou em outros sistemas e os retorna para o cliente.
  • Os dados retornados são formatados de acordo com as regras estabelecidas pela API (geralmente JSON).

GraphQL

A comunicação por meio de GraphQL ocorre da seguinte maneira:

  1. O cliente envia uma solicitação POST à URI correspondente ao endpoint do GraphQL, contendo a query.
  2. A API recebe a solicitação e processa a query para determinar quais recursos precisam ser acessados.
  3. Em seguida, o servidor busca os dados relacionados nos bancos de dados ou em outros sistemas.
  4. Os dados retornados são formatados de acordo com as regras estabelecidas pela API (geralmente JSON).
  5. A resposta é enviada ao cliente, contendo apenas os dados solicitados.

Comparação entre API REST e GraphQL

API RESTGraphQL
Especificar requisiçõesNão há suporte à especificação de requisições personalizadasPode-se especificar requisições personalizadas por meio da query.

Observações importantes sobre o funcionamento interno dos dois modelos:

  • A API REST segue os princípios do modelo REST, enquanto GraphQL adota uma abordagem mais flexível e adaptável às necessidades específicas de cada cliente.
  • A escolha entre esses dois modelos depende das características específicas do sistema em desenvolvimento.

Exemplo real

Vamos considerar um exemplo de uso onde temos uma aplicação web que utiliza informações dos usuários para exibir uma lista personalizada de produtos. O sistema tem os seguintes requisitos:

  • Os produtos devem ser filtrados por categorias.
  • Os resultados devem incluir o preço do produto, a descrição e a imagem.
  • Além disso, queremos que o cliente possa especificar quais campos devem ou não ser retornados.

Aqui está um exemplo de como isso pode ser implementado utilizando API REST:


from flask import Flask, jsonify

app = Flask(__name__)

produtos = {
    "produto1": {"nome": "Produto 1", "preco": 10.99, "descricao": "Descrição do produto 1"},
    "produto2": {"nome": "Produto 2", "preco": 9.99, "descricao": "Descrição do produto 2"}
}

@app.route("/produtos/<string:categoria>", methods=["GET"])
def get_produtos(categoria):
    # Filtrando produtos por categoria
    produtos_categoria = {k: v for k, v in produtos.items() if v["nome"].startswith(categoria)}

    # Formatando a resposta com os campos desejados
    resposta = {"produtos": [{"nome": produto["nome"], "preco": produto["preco"]} for produto in produtos_categoria.values()]}

    return jsonify(resposta)

if __name__ == "__main__":
    app.run(debug=True)

Essa API REST, no entanto, não permite especificar quais campos precisam ser retornados e nem suporta a query de busca personalizada.

Agora vamos ver como implementar o mesmo exemplo utilizando GraphQL:


import graphene

class Produto(graphene.ObjectType):
    nome = graphene.String()
    preco = graphene.Float()
    descricao = graphene.String()

    @staticmethod
    def resolve_imagem(root, info):
        # Simulando a busca de imagem de produto
        return "https://example.com/imagens/" + root.nome

class Query(graphene.ObjectType):
    produto = graphene.Field(Produto)
    produtos = graphene.List(Produto)

    def resolve_produto(self, info, nome=None):
        # Buscando produto pelo nome (se fornecido)
        if nome:
            return Produto(nome=nome, preco=9.99, descricao="Descrição do produto")
        else:
            return None

    def resolve_produtos(self, info):
        # Retornando uma lista de produtos
        return [
            Produto(nome="Produto 1", preco=10.99, descricao="Descrição do produto 1"),
            Produto(nome="Produto 2", preco=9.99, descricao="Descrição do produto 2")
        ]

schema = graphene.Schema(query=Query)

query1 = """
query {
  produtos {
    nome
    preco
  }
}
"""

result1 = schema.execute(query1)
print(result1.data["produtos"])

query2 = """
query {
  produto(nome: "Produto 1") {
    nome
    preco
    descricao
    imagem
  }
}
"""
result2 = schema.execute(query2)
print(result2.data["produto"])

Nesse exemplo, a API GraphQL permite que o cliente especifique quais campos precisam ser retornados e executa queries de busca personalizadas.

Boas práticas

Use caching para melhorar desempenho

Implemente um cache nos resultados das consultas GraphQL para evitar a sobrecarga de solicitações repetidas ao servidor.

Utilize Introspecção

A introspecção permite que os clientes descubram as respostas disponíveis e seus tipos. Isso pode ser útil para ferramentas de desenvolvimento, mas também pode ser um problema de segurança se não for configurado corretamente.

Armadilhas comuns

Sobrecarga de solicitações GraphQL

A API GraphQL permite que os clientes solicitem todos os campos possíveis em uma query. Isso pode levar a uma sobrecarga no servidor, especialmente se os campos solicitados forem muitos ou complexos.

Falha ao lidar com dados paginados

A API GraphQL não tem suporte nativo para dados paginados. Se você está lidando com conjuntos de dados muito grandes, é importante implementar um sistema de paginação personalizado para evitar problemas de desempenho.

Conclusão

A escolha entre API REST e GraphQL depende das necessidades específicas do seu projeto. Se você precisa de uma comunicação flexível e personalizável, onde os clientes possam solicitar apenas os campos necessários, GraphQL pode ser a melhor opção. No entanto, é importante considerar as desvantagens de usar GraphQL, como a sobrecarga de solicitações e a complexidade adicional que isso traz.

Ao implementar uma API GraphQL, é crucial seguir boas práticas, como o uso de caching e introspecção, para evitar problemas comuns. Além disso, é essencial desenvolver habilidades em resolver armadilhas, como lidar com dados paginados e evitando a sobrecarga de solicitações.

Para aprofundar sua compreensão sobre a seleção do modelo de comunicação certo para seu projeto, você pode considerar aprender mais sobre:

  • Desenvolvimento de APIs RESTful
  • Implementação de paginação em APIs GraphQL
  • Uso efetivo de caching e introspecção em APIs GraphQL

Referências

  • Fielding, R. T. Architectural Styles and the Design of Network-based Software Architectures. 2000.
  • Martin Fowler. API: A List of Things They Should Have. Disponível em: https://martinfowler.com/articles/a-list-of-things-their-apis-should-have.html. Acesso: 2024.
  • Thoughtworks. GraphQL vs REST: Comparing Two Approaches to Building APIs. Disponível em: https://www.thoughtworks.com/insights/blog/graphql-vs-rest-comparing-two-approaches-building-apis. Acesso: 2024.
  • The GraphQL Documentation. What is the difference between GraphQL and REST? Disponível em: https://www.graphql.org/learn/frequently-asked-questions/. Acesso: 2024.
  • OWASP. RESTful APIs Security Considerations. Disponível em: https://owasp.org/www-project-restful-api-security/. Acesso: 2024.