Using GraphQL in iOS with the ApolloClient and CocoaPods

Apollo 17 astronaut Gene Cernan in 1972

I recently tried adding GraphQL to a new iOS project using the ApolloClient and was surprised at the number of articles that referenced only how to use the legacy ApolloClient (v0.x). The official documentation referenced how to use the v1 but only with swiftPackageManager.

Since this project was using CocoaPods, I decided to document how to go about that.

Installation

1. Add Apollo to your Podfile

pod "Apollo"

2. (Optional) Include to your Podfile the ApolloSQLite and ApolloWebSocket framework if you need them

pod "Apollo/SQLite"
pod "Apollo/WebSocket"

3. Run pod install

Codegen Configuration

You need to setup your Codegen Configuration file. This guides Apollo how to handle the code generation for your file. You can find out more here. You would be using the Apollo iOS CLI which comes bundled with the Pod, this would be at /Pods/Apollo/apollo-ios-cli

1. Open a Terminal at the project directory. Ideally, this would be where your Assets.xcassets, Base.lproj, Info.plist were created
2. Run the following command below, replacing “NameOfAPI” with what you want to call the call and “NameOfTarget” with the name of the target in your iOS project.

../Pods/Apollo/apollo-ios-cli init --schema-namespace NameOfAPI --target-name NameOfTarget --module-type embeddedInTarget

Take note of the module-type args, we are telling Apollo that you are responsible for adding the generated graphql swift classes to your target and not the ApolloClient. This seems to currently be the only option that works with CocoaPods.

3. This would generate a apollo-codegen-config.json file tailored to your project. You would find it in your project directory.

Download your server’s schema

You are going to download the schema for your project to use. Edit the just generated apollo-codegen-config.json file and add a schemaDownloadConfiguration section. Add the section below just after the output object not forgetting to add your graphql endpoint.

"schemaDownloadConfiguration": {
  "downloadMethod": {
        "introspection": {
            "endpointURL": "your graphl endpoint",
            "httpMethod": {
                "POST": {}
            },
            "includeDeprecatedInputValues": false,
            "outputFormat": "SDL"
        }
    },
    "downloadTimeout": 60,
    "headers": [],
    "outputPath": "./graphql/schema.graphqls"
}

Next, run the following command in your project directory to download the schema.

../Pods/Apollo/apollo-ios-cli fetch-schema

You should see a graphql folder in your project directory after running this file. This folder contains a schema.graphqls file which contains the downloaded scheme from your server

Add your GraphQL querys to Xcode

1. In Xcode, add a new file, navigate to the Other section and select the Empty file template.
2. Name the file as you wish, ending with a .graphql extension. Add the file to the graphql folder that was created in the previous section, making sure to ensure that this file is NOT added to the app target. It’s very IMPORTANT.

3. Open the newly created file and paste in your graphql queries.

Code Generation

Time to generate code from our schema and query file(s). Run the following in your project directory

../Pods/Apollo/apollo-ios-cli generate

This generates your files and puts them in new folder named NameOfAPI in your project directory.

Add generated files to your target

Remember when you configured your codegen; you specified in the module-type args that you would be responsible for adding generated files to your target and not Apollo, the time is near.

Go to Xcode and add the NameOfAPI folder that was generated in the previous section. Making sure the add to target option is toggled. This would be your NameOfTarget target

Confirm that these files are added by checking your Compile Sources. Select your App Target, then Build Phases and open up the Compile Sources, your files should be in there.

Now you should have all you need to implement your graphql queries. Calling your query functions should always have the NameOfAPI preceding it, just like the example below;

Run your app and you should be set to go!

Thanks for reading! You can find me on Twitter: knightbenax or Posts.cv: knightbenax