GraphQL API com Swift: tutorial prático passo a passo

Introdução ao GraphQL e Swift

GraphQL é uma linguagem de consulta para APIs que permite aos clientes obter exatamente os dados de que precisam, sem excessos. Para desenvolvedores iOS e macOS, a integração com GraphQL abre novas possibilidades para criar aplicativos móveis eficientes e flexíveis. Neste tutorial, vamos abordar na prática como conectar uma GraphQL API a um projeto Swift, executar consultas e mutações básicas, além de tratar possíveis erros.

Ao contrário do REST tradicional, o GraphQL permite solicitar vários recursos em uma única requisição, o que é especialmente importante para dispositivos móveis com tráfego limitado. Usaremos a biblioteca popular Apollo iOS — a solução mais estável e documentada para trabalhar com GraphQL em Swift.

Preparação do projeto e instalação do Apollo iOS

Passo 1: Criar o projeto e instalar dependências

Abra o Xcode e crie um novo projeto iOS (ou macOS). Para trabalhar com GraphQL, instalaremos o Apollo iOS via Swift Package Manager (SPM).

\n
1. No Xcode, selecione File → Add Packages
\li>Insira a URL do repositório: https://github.com/apollographql/apollo-ios.git\li>Escolha a versão estável mais recente (no momento da escrita — 1.15+)\li>Adicione o pacote ao seu target

Passo 2: Geração de código a partir do esquema GraphQL

O Apollo iOS usa geração de código: você descreve as consultas em arquivos .graphql, e a ferramenta cria código Swift tipado. Para isso, é necessário:

\n
1. Crie uma pasta GraphQL no projeto
\li>Coloque lá o arquivo schema.graphqls (esquema da sua API) — geralmente pode ser obtido via introspecção\li>Crie um arquivo de consulta, por exemplo GetUser.graphql:

query GetUser($id: ID!) {\n  user(id: $id) {\n    id\n    name\n    email\n    posts {\n      title\n    }\n  }\n}

Em seguida, adicione uma Build Phase com a execução do gerador de código. A maneira mais fácil é instalar o Apollo CLI via Homebrew:

brew install apollo-ios-cli

E execute o comando na raiz do projeto:

./apollo-ios-cli generate

Depois disso, na pasta Sources/API, aparecerão os arquivos Swift gerados com os modelos de dados.

Executando consultas GraphQL básicas

Configuração do cliente Apollo

Crie uma instância do cliente Apollo, informando a URL do seu endpoint GraphQL. Geralmente, isso é feito no AppDelegate ou em uma classe de serviço separada:

import Apollo\n\nclass NetworkService {\n    static let shared = NetworkService()\n    private(set) lazy var apollo: ApolloClient = {\n        let url = URL(string: "https://your-api.com/graphql")!\n        return ApolloClient(url: url)\n    }()\n}

Consulta de dados (Query)

Agora, vamos executar uma consulta para obter um usuário. O código gerado criará a estrutura GetUserQuery:

import Foundation\n\nclass UserViewModel: ObservableObject {\n    @Published var user: User?\n    @Published var errorMessage: String?\n    \n    func fetchUser(id: String) {\n        NetworkService.shared.apollo.fetch(query: GetUserQuery(id: id)) { [weak self] result in\n            DispatchQueue.main.async {\n                switch result {\n                case .success(let graphQLResult):\n                    if let userData = graphQLResult.data?.user {\n                        self?.user = User(\n                            id: userData.id,\n                            name: userData.name,\n                            email: userData.email\n                        )\n                    }\n                case .failure(let error):\n                    self?.errorMessage = "Erro: \\(error.localizedDescription)"\n                }\n            }\n        }\n    }\n}

Observe: usamos @Published para atualização reativa da UI em