GraphQL with Apollo iOS SDK

Here I am going to show a step by step implementation on how to use Apollo iOS SDK in your swift application. In my guide I would be Apollo iOS SDK for a tvOS application which uses https://api.spacex.land/graphql/ api.

The application hits the Spacex api and queries all the past missions and displays it.

SpaceX’s missions

Mission Details

What is GraphQL?

GraphQL is a query language for APIs and a runtime for fulfilling those queries with your existing data. GraphQL provides a complete and understandable description of the data in your API, gives clients the power to ask for exactly what they need and nothing more, makes it easier to evolve APIs over time, and enables powerful developer tools.

Source: https://graphql.org/

What is Apollo Client?

“Apollo iOS is a strongly-typed, caching GraphQL client for iOS, written in Swift. It allows you to execute queries and mutations against a GraphQL server, and returns results as query-specific Swift types. This means you don’t have to deal with manually parsing JSON”

Source: https://www.apollographql.com/docs/ios/

The Apollo website has excellent documentation. I would like to share step by step implementation in using Apollo iOS SDK.

Step 1: Adding Apollo SDK to the project

Create the project. Add the dependency using Swift Package Manager into your project and follow all the steps exactly as in https://www.apollographql.com/docs/ios/tutorial/tutorial-create-project/.

Note: Do not select the Apollo-Dynamic target when selecting the target to add to the project, this is only for use for projects linking to our library dynamically. Most projects, including this one, will not need to do this.

Step 2: Obtain your GraphQL schema and create your query

The Apollo iOS SDK needs two elements to automatically generate the model types and the code(API.swift) that the it uses to interact with your server namely,

1. Local copy of your server’s schema (schema.json)
2. Query (YourQuery.graphql)

The api which I am going to use is an open source SpaceX database https://api.spacex.land/graphql/ for our tvOS application.

A. Server schema (schema.json)

The schema defines which GraphQL operations your server can execute. In https://api.spacex.land/graphql/ click the explorer on the left-hand side to view a list of types you can query (and the types of fields on those types).

To get the schema for a given graphql api do the following steps,

1. Install ‘get-graphql-schema’ from the node package manager https://www.npmjs.com/package/get-graphql-schema
2. Execute the command “get-graphql-schema https://api.spacex.land/graphql — json > schema.json” inside a folder of your choice. This will generate the ‘schema.json’ file.
3. Drag and drop the ‘schema.json’ file to the same level as Appdelegate.swift in your project folder structure. Don’t add it to any target when adding the file to the project

For detailed step by step instruction with screenshots please see https://www.apollographql.com/docs/ios/tutorial/tutorial-obtain-schema/

If you are able to do up-to this give a pat to yourself, you have crossed the trickiest part.

B. Creating query (query.graphql)

The Apollo iOS SDK requires every query to have a name. The query I am going to create has the name ‘LauchList’.

In the middle panel of https://api.spacex.land/graphql/, you see both the query itself and information about what the query returns. You can use this information to write a query you’ll eventually add to your app. Copy the query and use it.

1. Create LaunchList.graphql file in xcode and create the query.graphql file as clearly described here. Make sure you paste the copied query in this format,

‘query QuerName {

“Your copied query structure goes here”

}’.

As the schema indicates, the query returns an array of SpaceX LaunchesPast object. The created LauchList.graphql looks like below,

schema.json

2. Make sure it is saved at the same level as your schema.json file. As previously, don’t add it to any target.

After adding the schema.json and LaunchList.graphql in the application folder

For detailed steps regarding creating the query please refer https://www.apollographql.com/docs/ios/tutorial/tutorial-execute-query/

Step 3: Running the code generation (API.swift)

You’re now ready to generate API.swift that contains the model types and the code that the SDK uses to interact with your server from the combination of your saved query and schema in your project.

1. On your application target’s Build Phases settings tab, click the + icon and choose New Run Script Phase.
2. In the created Run Script, change its name to Apollo CLI.
3. Drag this new run script just above Compile Sources in your list of Build Phases so that it executes before your code is compiled.
4. Add the contents of the appropriate run script for the package manager you’re using as in below,

Build Phase script

After adding the build phase script

5. Build your project. When the build completes, an API.swift file appears in the same folder as schema.json.

6. Drag the API.swift file into Xcode. This time, do check the Add to target box for the your app. You include this file in your application's bundle to enable you to execute the query you defined.

See the API.swift generated in the applications root folder

Add application target

After pasting API.swift

Open the API.swift file. It defines a root class, with many nested structs below it. If you compare the structs to the JSON data returned in GraphQL, you see that the structure matches. These structs include properties only for the fields that query requests in the .graphql file.

For detailed reference see https://www.apollographql.com/docs/ios/tutorial/tutorial-execute-query/

Step 4: Running End-End

1. Create a new Swift file called Network.swift

2. To make the network call use the below implementation,

For the full code please find here.

Happy coding. Any thoughts or help if you need please feel free to reach me at pratheesh_db@hotmail.com. I would be happy to help you 24x7.

References:

Introduction

A query language for your API