Apollo iOS tutorial

In order to pull data from the new Contentful GraphQL endpoint, you need to integrate a GraphQL client library that handles sending GraphQL queries and parsing the corresponding responses. The Apollo SDK for iOS is one of the most popular choices for a GraphQL client.

Overview

The workflow when working with a GraphQL endpoint and the Apollo SDK is as follows:

• Use the Apollo CLI to introspect the GraphQL schema for your content model and include it in your project.
• Write and test your queries using GraphiQL or your preferred GraphQL playground tool.
• Use the Apollo CLI to generate Swift model types from your schema and queries.
• Integrate ApolloClient into your app, passing in the generated Swift queries; write the logic for handling already-parsed responses.

Prerequisite

Before continuing with this guide, refer to the Apollo iOS documentation to find instructions on adding the Apollo SDK for iOS to your project, and ensure you have the Apollo CLI installed on your machine.

Download your schema

ApolloClient has generic fetch(query:) methods that take a query argument conforming to the Apollo.GraphQLQuery protocol. Instead of constructing all your Swift query models manually, you can generate Swift code for your query models. To do this, first download the GraphQL schema for your content model using the Apollo CLI and place it in your project’s root directory:

apollo schema:download --header "Authorization: Bearer $ACCESS_TOKEN" \
--endpoint https://graphql.contentful.com/content/v1/spaces/$SPACE_ID/environments/master

Write your GraphQL queries

Use a GraphQL playground, such as GraphiQL to test your GraphQL queries. Contentful provides a GraphiQL interface to test your queries in the browser at https://graphql.contentful.com/content/v1/spaces/$SPACE_ID/environments/master/explore?access_token=$ACCESS_TOKEN

Note: Use one GraphQL fragment for each content type in your .graphql files so that there is a unified representation in Swift for each content type. In order to avoid name clashes with the deeply nested types that Apollo generates, it is recommended that the suffix “Fragment” is added for each fragment you write. For example, ProductFragment instead of Product.

Generate Swift query models

Once your queries are working and return the expected data, run the following command to generate the Swift file that holds all your queries and fragments. The last argument is the path to your file.

apollo codegen:generate --target=swift --schema=schema.json --queries=$YOUR_QUERY_FILE.graphql Path/to/QueryModelFile.swift

Fetch data with ApolloClient

Since the fetch method is generic and Apollo.GraphQLQuery protocol has associated type constraints, the callback method returns strongly-typed, objects upon a successful API response. In the following example, CoursesQuery is query type generated by the Apollo CLI.

apolloClient.fetch(query: CoursesQuery()) { [weak self] result, error in
    // Handle the response here.
}

The ApolloClient.fetch(query:) method has several other arguments for choosing the callback execution queue, among other options. Refer to the Apollo iOS SDK documentation to see all the options.

Example app with the Contentful GraphQL endpoint and Apollo iOS

Contentful has an example application on Github that demonstrates using the GraphQL endpoint and the Apollo iOS SDK together. In the project directory, you can find a bash script for downloading the schema and generating model files, the GraphQL queries for the app, and example API calls using ApolloClient.