Apollo iOS 1.0 migration guide

Apollo iOS 1.0 provides a stable API that uses modern Swift language conventions and features.

Among other improvements, Apollo iOS 1.0 features new:

• Code generation tooling written in pure Swift code.
• Generated models that improve readability and functionality while reducing generated code size.
• Support for using generated models in multi-module projects.
• Type-safe APIs for cache key resolution.

This article describes the significant changes for this major version of Apollo iOS and a walk-through of migrating an existing project from Apollo iOS 0.x to 1.0.

Key changes

Generated schema module

The 0.x version of Apollo iOS generates models for your GraphQL operation definitions and the input objects and enums referenced in your schema.

Apollo iOS 1.0 expands on this, generating an entire module that contains models and metadata for your GraphQL schema and its type definitions.

In addition to your input objects and enum types, this module contains:

• Types for the objects, interfaces, and unions in your schema.
• Editable definitions for your custom scalars.
• An editable SchemaConfiguration.swift file.
• Metadata for the Apollo GraphQL executor.

Schema types are contained in their own namespace to prevent naming conflicts. You can generate this namespace as a stand-alone module, imported by your project, or as a caseless namespace enum that you can embed in your application target.

Multi-module support

Apollo iOS 1.0 can support complex applications composed of multiple modules or monolithic application targets.

The generated schema module supports multi-module projects by containing all of a schema's shared types and metadata. This enables you to move generated operation models anywhere within your project structure (as long as they are linked to the schema module).

Apollo iOS's code generation engine provides flexible configuration options that make code generation work seamlessly for any project structure.

Step-by-step instructions

To migrate to Apollo iOS 1.0, you'll do the following:

1. Update your Apollo iOS dependency
2. Setup code generation
3. Replace the code generation build phase
4. Refactor your code to use new APIs

Much of this migration process involves the new code generation mechanism.

As you go through this process, we'll explain how to remove deprecated pieces of the legacy 0.x version along the way. Each of the following steps also includes explanations for any breaking API changes.

Step 1: Upgrade to Apollo iOS 1.0

Begin by updating your Apollo iOS dependency to the latest version. You can include Apollo iOS as a package using Swift Package Manager (SPM) or Cocoapods.

To receive bug fixes and new features, we recommend including 1.0 up to the next major release.

.package(
  url: "https://github.com/apollographql/apollo-ios.git",
  .upToNextMajor(from: "1.0.0")
),

pod 'Apollo' ~> '1.0'

Step 2: Set up code generation

Apollo iOS 1.0 includes a new code generation engine, written in pure Swift code, replacing the legacy apollo-tooling library. To use 1.0, you must install the new code generation engine and remove the old one.

We recommend running the new code generation engine using the Apollo Codegen CLI. You can also run code generation in a Swift script for more advanced usage.

Codegen CLI setup

For CLI setup instructions, select the method you are using to include Apollo.

Swift scripts setup

If you are running code generation via a Swift script, update your script to use the version of ApolloCodgenLib that matches your Apollo version.

Then, update the ApolloCodegenConfiguration in your script with the new configuration values. For a list of configuration options, see Codegen configuration.

Step 3: Replace the code generation build phase

Your generated files change whenever you modify your .graphql operation definitions (which happens infrequently). Running code generation on every build increases build times and slows development.

Instead, we recommend running code generation manually (using the CLI) whenever you modify your .graphql files.

If you want to continue running code generation on each build, you can update your build script to run the CLI generate command.

Step 4: Refactor your code

While designing Apollo iOS 1.0, we tried to limit the number of code changes required to migrate from legacy versions.

Below are explanations for each breaking change that Apollo iOS 1.0 brings and tips on addressing those changes during your migration.

Breaking changes

Custom scalars

In the 0.x version of Apollo iOS, your schema's custom scalars are exposed as a String type field by default. If you used the --passthroughCustomScalars option, your generated models included the name of the custom scalar. You were responsible for defining the types passed through to your custom scalars.

In Apollo iOS 1.0, operation models use custom scalar definitions, and by default, Apollo iOS generates typealias definitions for all referenced custom scalars. These definitions are within your schema module. The default implementation of all custom scalars is a typealias to String.

To migrate a custom scalar type to Apollo iOS 1.0, do the following:

• Include the type in your schema module.
• Ensure the type conforms to the CustomScalarType protocol.
• Point the typealias definition to the new type.
  • Or, if the type has the exact name of your custom scalar, remove the typealias definition.

Example

We define a scalar Coordinate, which we reference in our GraphQL operations. Apollo iOS generates the Coordinate custom scalar:

1
public extension MySchema {
2
  typealias Coordinate = String
3
}

A custom scalar with the name Coordinate could replace the typealias, like so:

1
public extension MySchema {
2
  struct Coordinate: CustomScalarType {
3
    let x: Int
4
    let y: Int
5

6
    public init (_jsonValue value: JSONValue) throws {
7
      guard let value = value as? String,
8
        let coordinates = value.components(separatedBy: ",").compactMap({ Int($0) }),
9
        coordinates.count == 2 else {
10
        throw JSONDecodingError.couldNotConvert(value: value, to: Coordinate.self)
11
      }
12

13
      self.x = coordinates[0]
14
      self.y = coordinates[1]
15
    }
16

17
    public var _jsonValue: JSONValue {
18
      "\(x),\(y)"
19
    }
20
  }
21
}

Cache key configuration

In the 0.x version of Apollo iOS, you could configure the computation of cache keys for the normalized cache by providing a cacheKeyForObject block to ApolloClient.

In Apollo iOS 1.0, we replace this with a type-safe API in the SchemaConfiguration.swift file, which Apollo iOS generates alongside the generated schema types.

To migrate your cache key configuration code, refactor your cacheKeyForObject implementation into the SchemaConfiguration.swift file's cacheKeyInfo(for type:object:) function. This function needs to return a CacheKeyInfo struct (instead of a cache key String).

In 0.x, we recommended that you prefix your cache keys with the __typename of the object to prevent key conflicts.

Apollo iOS 1.0 does this automatically. If you want to group cache keys for objects of different types (e.g., by a common interface type), you can set the uniqueKeyGroup property of the CacheKeyInfo you return.

Example

Given a cacheKeyForObject block:

1
client.cacheKeyForObject = {
2
  guard let typename = $0["__typename"] as? String,
3
    let id = $0["id"] as? String else {
4
      return nil
5
    }
6

7
  return "\(typename):\(id)"
8
}

You can migrate this to the new cacheKeyInfo(for type:object:) function like so:

1
public enum SchemaConfiguration: ApolloAPI.SchemaConfiguration {
2
  static func cacheKeyInfo(for type: Object, object: JSONObject) -> CacheKeyInfo? {
3
    guard let id = object["id"] as? String else {
4
      return nil
5
    }
6

7
    return CacheKeyInfo(id: id)
8
  }
9
}

Or you can use the JSON value convenience initializer, like so:

1
public enum SchemaConfiguration: ApolloAPI.SchemaConfiguration {
2
  static func cacheKeyInfo(for type: Object, object: JSONObject) -> CacheKeyInfo? {
3
    return try? CacheKeyInfo(jsonValue: object["id"])
4
  }
5
}

Local Cache Mutations

In the 0.x version of Apollo iOS, you could directly change data in the local cache using any of your generated operation or fragment models.

The APIs for direct cache access have mostly stayed the same but generated model objects are now immutable by default. You can still read cache data directly using your generated models, but to mutate cache data, you now need to define separate local cache mutation operations or fragments.

You can define a local cache mutation model by applying the @apollo_client_ios_localCacheMutation directive to any GraphQL operation or fragment definition.

Example

Given an operation and write transaction from Apollo iOS 0.x versions:

query UserDetails {
  loggedInUser {
    id
    name
    posts {
      id
      body
    }
  }
}

store.withinReadWriteTransaction({ transaction in
  let cacheMutation = UserDetailsQuery()

  let newPost = UserDetailsQuery.Data.LoggedInUser.Post(id: "789, body: "This is a new post!")

  try transaction.update(cacheMutation) { (data: inout UserDetailsQuery.Data) in
    data.loggedInUser.posts.append(newPost)
  }
})

In Apollo iOS 1.0, you can rewrite this using a new LocalCacheMutation:

query AddUserPostLocalCacheMutation @apollo_client_ios_localCacheMutation {
  loggedInUser {
    posts {
      id
      body
    }
  }
}

store.withinReadWriteTransaction({ transaction in
  let cacheMutation = AddUserPostLocalCacheMutation()

  let newPost = AddUserPostLocalCacheMutation.Data.LoggedInUser.Post(data: DataDict(
    ["__typename": "Post", "id": "789", "body": "This is a new post!"],
    variables: nil
  ))

  try transaction.update(cacheMutation) { (data: inout AddUserPostLocalCacheMutation.Data) in
    data.loggedInUser.posts.append(newPost)
  }
})

Nullable Input Values

According to the GraphQL spec, explicitly providing null as the value for an input field is semantically different from not providing a value (nil).

To distinguish between null and nil, the 0.x version of Apollo iOS generated optional input values as double optional value types (??, or Optional<Optional<Value>>). This was confusing for many users and didn't clearly express the intention of the API.

In Apollo iOS 1.0, we replaced the double optional values with a new GraphQLNullable wrapper enum type.

This new type requires you to indicate your input fields' value or nullability behavior explicitly. This applies to nullable input arguments on your operation definitions and nullable properties on input objects.

While this API is slightly more verbose, it provides clarity and reduced bugs caused by unexpected behavior.

Example

If we are passing a value to a nullable input parameter, we'll need to wrap that value in a GraphQLNullable:

MyQuery(input: "Value")

MyQuery(input: .some("Value"))

To provide a null or nil value, use .null or .none, respectively.

/// A `nil` double optional value translates to omission of the value.
MyQuery(input: nil)

/// An optional containing a `nil` value translates to an `null` value.
MyQuery(input: .some(nil))

/// A `GraphQLNullable.none` value translates to omission of the value.
MyQuery(input: .none)

/// A `GraphQLNullable.null` value translates to an `null` value.
MyQuery(input: .null)

When passing an optional value to a nullable input value, you need to provide a fallback value if your value is nil:

var optionalInput: String?  = nil

MyQuery(input: optionalInput)

var optionalInput: String?  = nil

MyQuery(input: optionalInput ?? .null)

Mocking operation models for testing

In the 0.x version of Apollo iOS, you could create mocks of your generated operation models by using each model's generated initializers or by initializing them directly with JSON data. Both methods were error-prone, cumbersome, and fragile.

Apollo iOS 1.0 provides a new way to generate test mocks based on your schema types. Begin by adding output.testMocks to your code generation configuration, then link your generated test mocks to your unit test target.

Instead of creating a model using a type's generated initializer, you create a test mock of the schema type for the underlying object. Using the test mock, you can set values for relevant fields and initialize your operation model.

Apollo iOS 1.0's new test mocks are more comprehensible and type-safe. They also remove the need for generated initializers for different model types.

Note, you can continue initializing your operation models with JSON data, but the initializer has changed slightly. For more information, See JSON initializer.

Examples

Given a Hero interface type that can be either a Human or Droid type, and the following operation definition:

1
query HeroDetails {
2
  hero {
3
    id
4
    ... on Human {
5
      name
6
    }
7
    ... on Droid {
8
      modelNumber
9
    }
10
  }
11
}

The 0.x version of Apollo iOS generates initializers for each type on the HeroDetails.Data.Hero model:

1
struct Hero {
2
  static func makeHuman(id: String, name: String) {
3
    // ...
4
  }
5

6
  static func makeDroid(id: String, modelNumber: String) {
7
    // ...
8
  }
9
}

These initializers are not generated in Apollo iOS 1.0. Instead, you can initialize either a Mock<Human>, or a Mock<Droid>:

1
let mockHuman = Mock<Human>()
2
mockHuman.id = "10"
3
mockHuman.name = "Han Solo"
4

5
let mockDroid = Mock<Droid>()
6
mockDroid.id = "12"
7
mockDroid.modelNumber = "R2-D2"

Then, create mocks of the HeroDetails.Data.Hero model using your test mocks:

1
let humanHero = HeroDetails.Data.Hero(from: mockHuman)
2
let droidHero = HeroDetails.Data.Hero(from: mockDroid)

Test mocks from JSON Data

If you want to continue initializing your models using JSON data directly, you can update your initializers to create your model using the init(data: DataDict) initializer. You must also ensure that your JSON data is a [String: AnyHashable] dictionary.

let json: [String: Any] = [
  "__typename: "Human",
  // ...
]

let hero = HeroDetails.Data.Hero(
  unsafeResultMap: json
)

let json: [String: AnyHashable] = [
  "__typename: "Human",
  // ...
]

let hero = HeroDetails.Data.Hero(
  data: DataDict(json)
)