GraphQL Using the Apollo Framework: Getting Started

Do you ever feel frustrated when working with a REST API? Do endpoints sometimes not give you the data you need for your app? Do you have to make multiple requests, or change your back end, to get the right information from the server? Well, worry no more! It’s GraphQL and the Apollo Framework to the rescue!

GraphQL is an open-source API design paradigm. Facebook introduced GraphQL in 2012, and it’s been powering Facebook’s mobile apps ever since. In contrast to REST, a GraphQL API exposes only a single endpoint, and the consumers of the API can specify the data they need via a query language.

GraphQL has been open-source since 2015. As its popularity has increased, a robust open-source community has grown around it. This community has developed client libraries and IDE tools. One of the most popular of these projects is Apollo. Apollo is a type-safe caching implementation of GraphQL, available on multiple platforms.

Using the Apollo Framework, you’ll find it simple to:

• Consume a GraphQL schema.
• Auto-generate code from the model specification.
• Fetch data for any GraphQL endpoint.

As you work through the exercises in this tutorial, you’ll focus on setting up a local GraphQL development environment and fetching data from it. In the process, you’ll learn how to use the Apollo Framework to generate Swift code based on server queries and data schema. And you’ll use it to communicate with your server to fetch the data you need.

Getting Started

In this tutorial, you’ll build an app to display information about the films in the Star Wars universe. Download the starter project by clicking the Download Materials button at the top or bottom of the tutorial. Go to the Starter folder and open JediArchives.xcodeproj inside the Jedi Archives folder.

Now take a look at the project structure.

This project has three view controllers:

• FilmsViewController contains the list of movies.
• FilmDetailsViewController contains the movie information, such as the director and release date.
• CharacterDetailsViewController contains information about the characters in the selected movie.

The project also includes some interesting files needed for Apollo and GraphQL. You’ll see how they work as you go through the exercises in the tutorial:

• Apollo.swift: You’ll create a client to interface with the Apollo framework here.
• Queries.graphql: Your GraphQL queries will go here.
• API.swift: The Apollo Framework will automatically generate the model and API Swift code here.

Now, build and run. You’ll see the application — but you won’t see any films in the list!

The app’s user interface is complete, but empty. You’ll use Apollo to read the information from a server and display all the awesome Star Wars movies in the app. To do that, you’ll need a GraphQL server to provide the data. You’ll set up that server next.

Running Your GraphQL Server

You’re going to use the Star Wars API to get the movie information for the application. This API uses REST services. And, unfortunately, that means you can’t access it using GraphQL.

Fortunately, though, there’s an open-source project for this! The SWAPI GraphQL wrapper uses GraphQL to access the Star Wars API.

In the tutorial materials, you’ll find a SWAPI GraphQL folder which contains a pre-configured Node.js project that creates a local server. It then uses the SWAPI GraphQL wrapper to serve the information to your app using GraphQL.

To run the server, you need to make sure you have Node.js installed. If you don’t have it, visit Node.js for installation instructions.

With Node.js ready, it’s time to install Yarn. You’ll use Yarn to build and run the server. Open a terminal window and run the following command:

sudo npm install -g yarn

Next, you’ll build and run your GraphQL server. This is the server your app will connect to.

Then, to complete your Homebrew installation, run the following command to install pkg-config:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"

brew install pkg-config

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"

brew install pkg-config

Now go to the tutorial materials. You’ll find the server in the SWAPI GraphQL folder. Navigate to that folder. In your terminal window, type the following command:

cd

Be sure to add a space following the cd command. Then, drag the SWAPI GraphQL folder and drop it into the terminal. This will write the folder location in the terminal, and you won’t need to type it. Press Enter to change to the new directory.

Now, to build the server, run this command:

yarn

Wait for the command to finish, and then run the following command to start your GraphQL server:

yarn start

After you run this last command, your terminal window will display a localhost URL as well as a port, like this:

$ node lib/server
Listening at http://localhost:57881

Make a note of the port number. You’ll need it later for your app to communicate with the local server.

Great work! Now you’re all set up on the server side, and you’re ready to work on your app.

Installing the Apollo Framework

With your server up and running, it’s time to install the Apollo Framework. You’ll use the Swift Package Manager for this.

Adding Apollo as a Swift Package

Go back to Xcode, and select File ▸ Swift Packages ▸ Add Package Dependency….

In the next screen, paste https://github.com/apollographql/apollo-ios.git into the Choose Package Repository search box. Click Next. This will add Apollo as a Swift package.

Now, select Up To Next Minor and click Next.

In the next screen, select the Apollo package and click Finish.

Xcode will download the necessary packages and add the dependencies to your project.

Awesome! You’ve added Apollo as a Swift package, but there are still a few more steps needed to get it all working.