Up to speed with Apollo and GraphQL for Swift in 2023

If you haven’t followed along with GraphQL and Apollo, you might find it confusing when you start your Swift app that calls a GraphQL endpoint.

Installing the Swift package for Apollo is the easy part.

To ensure that your project is properly configured, make sure that the correct framework is linked in the general tab of your target. Beginning with Apollo alone should suffice.

Preparing for code generation

Generating code to access an API might feel strange if you haven’t used something like Apollo before. You might encounter documentation for the legacy version when searching for answers. I want to help you avoid some of the pitfalls I encountered in 2023.

Breaking changes came with Apollo version 1.0; the library is now on 1.2.1. For example, code generation is no longer recommended to be added to a run script phase. Instead, they recommend generating code from the command line.

But Xcode 14.3 has no menu command for installing Apollo iOS CLI because the plugin is not working, even though it works in Xcode 14.2. Also, adding apollo-ios-cli at the “Choose frameworks and libraries to add:” window doesn’t appear to work either. What is needed instead is to grab the Apollo CLI binary from their release page on GitHub. It exists as a separate gzip file.

Once you have the binary, you can run it from the command line. Note you shouldn’t run it from the top level of your project because it will recursively scan all subdirectories, including . git and others.

To generate code, you need a schema file. If you don’t have one, you can get it from your endpoint if it supports introspection after installing a tool like get-graphql-schema from npm, shown below.

$ npm install -g get-graphql-schema

Then you can download a schema with

$ get-graphql-schema ${YOUR_ENDPOINT} > schema.graphqls

Forming queries

That’s not all you need. No code will be generated if you don’t specify some queries or mutations. You will create these files using a .graphql extension instead of .graphqls for the schema.

For example, a query might look like the following:

query companyQuery {
    company {
        ceo
        coo
        cto
        cto_propulsion
        employees
        founded
        founder
        headquarters {
            address
            city
            state
        }
        launch_sites
        links {
            elon_twitter
            flickr
            twitter
            website
        }
        name
        summary
        test_sites
        valuation
        vehicles
    }
}

The above query is for a SpaceX API. It will give a result similar to what is listed below.

Code generation

You’ll also need a configuration file before you can run the code generator. One can be created with the following command:

$ ./apollo-ios-cli init --schema-namespace SpaceX --module-type embeddedInTarget --target-name MyApp --overwrite

After putting all the pieces together, you should be able to generate Swift code for a GraphQL API using the command listed below.

$ ./apollo-ios-cli generate -v

Since we generate code from the command line, we have to let our Xcode project know about any updates. Without a run script phase, you might have to manually update the generated code folder by deleting the reference to it and then re-adding it from the file system.

If in doubt about how Apollo is working, checking the generated code can answer most questions. All the types and functions available to you are listed there.

If you’re new to GraphQL or seeking a user-friendly interface, we highly recommend Altair GraphQL Client. It was instrumental for testing queries efficiently. Give it a try; it could be the tool you’ve been missing.

GraphQL summary

By the way, GraphQL endpoints are usually entirely accessible from a single URL.

In GraphQL, an object can have fields that return other objects or scalars. Scalars include strings, integers, floats, booleans, and enums. One key thing to remember is that every query must eventually resolve to a scalar or list of scalar types. Thinking about representing data in JSON might help you relate.

Finally, it is helpful to consider how GraphQL is often used to encapsulate access to a microservices architecture. It forms a standard interface someone can use to access data from many different services in a unified way even as the backend undergoes changes over time.

Therefore, knowing the basics of GraphQL can help you work with scalable data architectures.