GraphQL API com Swift: tutorial passo a passo para iniciantes

Introdução ao GraphQL e Swift

GraphQL é uma linguagem de consulta moderna para APIs, desenvolvida pelo Facebook. Diferente do REST, onde você recebe uma estrutura de dados fixa, o GraphQL permite que o cliente (seu aplicativo em Swift) solicite apenas os campos que realmente precisa. Isso é especialmente relevante para desenvolvedores mobile que trabalham com iOS e macOS: menos dados — menos tráfego, carregamento mais rápido, melhor UX.

Neste tutorial, vamos abordar como conectar uma GraphQL API ao seu projeto Swift, realizar consultas e mutações básicas. Usaremos o cliente oficial Apollo iOS — a biblioteca mais popular e suportada para trabalhar com GraphQL no ecossistema Apple.

Ao final do artigo, você será capaz de:

• Configurar o Apollo iOS em um projeto Xcode
• Escrever e executar uma consulta GraphQL (Query)
• Enviar uma mutação (Mutation) para alterar dados
• Processar respostas e erros

1. Configuração do projeto e instalação do Apollo iOS

1.1. Criando um novo projeto

Abra o Xcode e crie um novo projeto (iOS App ou macOS App). Escolha a linguagem Swift e a interface SwiftUI ou UIKit — não é relevante, pois o trabalho com rede não depende do framework de UI.

1.2. Instalação via Swift Package Manager

O Apollo iOS é facilmente conectado via SPM. Vá em File → Add Packages... e cole a URL:

https://github.com/apollographql/apollo-ios.git

Escolha a versão estável mais recente (no momento da escrita — 1.15.0) e adicione o pacote ao seu target.

Instale também o Apollo Code Generation CLI — ferramenta para gerar tipos Swift a partir do esquema GraphQL. A maneira mais fácil é instalá-lo via Homebrew:

brew install apollo-ios-cli

Se o Homebrew não estiver instalado, você pode usar npm:

npm install -g apollo-ios-cli

1.3. Inicialização da configuração

No terminal, a partir da raiz do seu projeto, execute:

apollo-ios-cli init --module-name YourAppName --schema-namespace GraphQL

Este comando criará o arquivo apollo-codegen-config.json e a pasta GraphQL, onde seus arquivos .graphql serão armazenados.

Agora adicione o esquema do servidor ao projeto. Se o servidor fornecer schema.json ou schema.graphqls, copie-o para a pasta GraphQL. Caso contrário, você pode usar o comando integrado para baixá-lo:

apollo-ios-cli fetch-schema --endpoint=https://your-graphql-endpoint.com/graphql

2. Escrevendo a primeira consulta GraphQL (Query)

2.1. Criando o arquivo .graphql

Na pasta GraphQL, crie um arquivo Queries.graphql e escreva uma consulta simples. Suponha que temos uma API para obter uma lista de usuários:

query GetUsers {  users {    id    name    email  }}

2.2. Geração do código Swift

Execute a geração de código no terminal:

apollo-ios-cli generate

Após a geração bem-sucedida, na pasta Sources/API (ou na que você especificou), aparecerá o arquivo API.swift com os tipos GetUsersQuery, GetUsersQuery.Data, etc.

2.3. Executando a consulta a partir do Swift

Agora vamos criar uma instância do cliente Apollo e executar a consulta. No seu ContentView.swift (ou qualquer outro arquivo), escreva:

import Apolloimport SwiftUI

class NetworkManager {    static let shared = NetworkManager()    private(set) lazy var apollo = ApolloClient(url: URL(string: "https://your-graphql-endpoint.com/graphql")!)}

struct ContentView: View {    @State private var users: [GetUsersQuery.Data.User] = []        var body: some View {        List(users, id: \\.id) { user in            VStack(alignment: .leading) {                Text(user.name)