Enhance customer experiences with Apollo GraphOS

Blog title is Mastering Cache Key Resolution in Apollo iOS with @typePolicy and @fieldPolicy

Mastering Cache Key Resolution in Apollo iOS with @typePolicy and @fieldPolicy


<p class="wp-block-paragraph">Did you know mobile application performance was the use case that drove the initial development of GraphQL? GraphQL has grown by leaps and bounds and is now used to power entire API platforms, but it remains an essential part of the mobile application developer’s toolkit.  To that end, we are excited to launch new, free courses for <a href="https://www.apollographql.com/tutorials/apollo-ios-swift-part1">iOS</a> and <a href="https://www.apollographql.com/tutorials/apollo-kotlin-android-part1">Android</a> developers in the Apollo Odyssey learning platform!</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="666" src="https://wp.apollographql.com/wp-content/uploads/2025/02/Screenshot-2024-09-03-at-1.23.36 PM-1024x666.png" alt="The image is a screenshot of a webpage from the Apollo GraphQL Odyssey tutorial series titled “Apollo iOS and Swift: Pagination, Mutations, and Subscriptions”. The tutorial section displayed is “Complete the details view”. The page includes a heading titled “Test the DetailView”, followed by instructions guiding users to build and run their application, verifying that clicking on a launch item navigates to a corresponding DetailView.

There are two prominent visuals on the page:
	1.	A screenshot of an Xcode editor showing SwiftUI code for handling the DetailView.
	2.	An iPhone simulator displaying a detailed launch view with a mission patch, launch details, and a “Book Now!” button.

The left sidebar contains a navigation menu with sections:
	•	Introduction
	•	Complete the details view (highlighted)
	•	Write your first mutation
	•	Authenticate your operations
	•	Define additional mutations
	•	Paginate results
	•	Write your first subscription

Below the main content, there is a paragraph mentioning that the “Book Now!” button has been added but isn’t functional yet, leading into the next section about making changes with GraphQL mutations, including authentication." class="wp-image-24074" srcset="https://wp.apollographql.com/wp-content/uploads/2025/02/Screenshot-2024-09-03-at-1.23.36 PM-1024x666.png 1024w, https://wp.apollographql.com/wp-content/uploads/2025/02/Screenshot-2024-09-03-at-1.23.36 PM-300x195.png 300w, https://wp.apollographql.com/wp-content/uploads/2025/02/Screenshot-2024-09-03-at-1.23.36 PM-768x499.png 768w, https://wp.apollographql.com/wp-content/uploads/2025/02/Screenshot-2024-09-03-at-1.23.36 PM-1536x999.png 1536w, https://wp.apollographql.com/wp-content/uploads/2025/02/Screenshot-2024-09-03-at-1.23.36 PM-2048x1332.png 2048w, https://wp.apollographql.com/wp-content/uploads/2025/02/Screenshot-2024-09-03-at-1.23.36 PM-1200x780.png 1200w, https://wp.apollographql.com/wp-content/uploads/2025/02/Screenshot-2024-09-03-at-1.23.36 PM-1980x1287.png 1980w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /></figure>



<h2 class="wp-block-heading"><a href="#apollo-ios-and-apollo-kotlin" aria-hidden="true" class="aal_anchor" id="apollo-ios-and-apollo-kotlin"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Apollo iOS and Apollo Kotlin</h2>



<p class="wp-block-paragraph">Apollo is proud to maintain the most widely-used free and open source GraphQL clients for web and mobile platforms.  <a href="https://www.apollographql.com/docs/ios">Apollo iOS</a> and <a href="https://www.apollographql.com/docs/kotlin">Apollo Kotlin</a> are trusted by thousands of iOS and Android teams to power their production applications written in Swift and Kotlin.  In order to fully leverage these industry-standard tools, a grasp of the fundamentals is essential.</p>



<p class="wp-block-paragraph">App development teams getting started with GraphQL now have access to new two-part courses:</p>



<ul class="wp-block-list">
<li><a href="https://www.apollographql.com/tutorials/apollo-ios-swift-part1">Apollo iOS and Swift</a></li>



<li><a href="https://www.apollographql.com/tutorials/apollo-kotlin-android-part1">Android Development with Apollo Kotlin</a></li>
</ul>



<p class="wp-block-paragraph">All of these courses are part of our expansive and free Apollo Odyssey platform.  There’s plenty more where that came from, too: check out our extensive library of courses for UI developers, backend developers, and platform engineers.</p>



<p class="wp-block-paragraph">If you have any ideas for new courses, please post your feedback in this <a href="https://community.apollographql.com/t/new-odyssey-courses-for-apollo-kotlin-and-apollo-ios-post-your-feedback-here/8678" data-type="link" data-id="https://community.apollographql.com/t/new-odyssey-courses-for-apollo-kotlin-and-apollo-ios-post-your-feedback-here/8678">Apollo Community thread</a>!  We’re always eager to hear what people want to learn about next.</p>


New GraphQL courses for iOS and Android development


<p class="wp-block-paragraph">The monorepo is a common structure for many software projects, and Apollo iOS is no different. Our project was structured in a single repo containing many different Swift Package Manager (SPM) library targets, along with test code and code only used as part of development. This presents a few problems however, one being that when a user adds the SPM package as a dependency, it will pull down all of the code and files in the repo, even though most of them aren’t needed. Another is that all of the individual libraries within the SPM package share the same version number.</p>



<p class="wp-block-paragraph">With this in mind, we set out to look for a way to restructure our libraries in such a way that we could provide users with smaller, more concise SPM packages, as well as give ourselves flexibility in providing separate features that can be versioned independently of the main Apollo iOS and Code Generation libraries.</p>



<p class="wp-block-paragraph">In thinking about what we wanted to achieve, the high-level goal became clear: separate our libraries into separate smaller repos which can be provided as their own SPM packages. However, separating the libraries out into different repositories could make the development and testing of the libraries much more difficult due to how they work together.</p>



<p class="wp-block-paragraph">So the question became how could we reach our end goal of providing separate library packages, while still maintaining an efficient development workflow?</p>



<h2 class="wp-block-heading"><a href="#git-submodules" aria-hidden="true" class="aal_anchor" id="git-submodules"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a><strong>Git Submodules</strong></h2>



<p class="wp-block-paragraph">The first thing we looked into was creating a development repo and using git submodules to include all of the SPM package repos so they could be developed in the same workspace together. The submodule functionality would pull down each SPM package repo into a sub-directory of the development repo, and keep a reference to the commit hash being referenced for each repo. This would solve one of our problems, which was to be able to develop and test all of our libraries together, while distributing them separately.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="535" src="https://wp.apollographql.com/wp-content/uploads/2024/01/Git-Submodules-1024x535.png" alt="" class="wp-image-23224" srcset="https://wp.apollographql.com/wp-content/uploads/2024/01/Git-Submodules-1024x535.png 1024w, https://wp.apollographql.com/wp-content/uploads/2024/01/Git-Submodules-300x157.png 300w, https://wp.apollographql.com/wp-content/uploads/2024/01/Git-Submodules-768x401.png 768w, https://wp.apollographql.com/wp-content/uploads/2024/01/Git-Submodules-1200x626.png 1200w, https://wp.apollographql.com/wp-content/uploads/2024/01/Git-Submodules.png 1272w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /></figure>



<p class="wp-block-paragraph">The downside to this is that we would have to manage changes in each submodule individually as well as always ensure the latest commit hash is checked out in the development repo when working on the libraries. This introduces a lot of overhead to the development process and opportunity for error.</p>



<p class="wp-block-paragraph">The other issue with this approach is that it meant changes for each library would need to be pushed in their own pull requests (PR) in their respective repo. Which means even though you may be working on a feature that contains changes across multiple SPM packages, you would not be able to review the PRs in a context which allows you to easily see and review all of the changes related to your work.</p>



<h2 class="wp-block-heading"><a href="#enter-git-subtree" aria-hidden="true" class="aal_anchor" id="enter-git-subtree"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a><strong>Enter Git Subtree</strong></h2>



<p class="wp-block-paragraph">In doing further research we came across the git subtree functionality. While this functionality is similar to git submodules, the way in which it functions is different. Instead of including separate repositories as sub-directories and references to commit hashes, the subtree functionality pulls all of the code of a repo into your repo from a specific reference, which can then be worked on independently as part of your repo. Although it can be worked on independently you can still push/pull changes to/from the remote repository.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="985" src="https://wp.apollographql.com/wp-content/uploads/2024/01/Git-Subtrees-1024x985.png" alt="" class="wp-image-23226" srcset="https://wp.apollographql.com/wp-content/uploads/2024/01/Git-Subtrees-1024x985.png 1024w, https://wp.apollographql.com/wp-content/uploads/2024/01/Git-Subtrees-300x289.png 300w, https://wp.apollographql.com/wp-content/uploads/2024/01/Git-Subtrees-768x739.png 768w, https://wp.apollographql.com/wp-content/uploads/2024/01/Git-Subtrees-1200x1154.png 1200w, https://wp.apollographql.com/wp-content/uploads/2024/01/Git-Subtrees.png 1237w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /></figure>



<p class="wp-block-paragraph">This seemed like a promising way to create our new repo structure, so we began working on a proof of concept to see if we could get the subtree functionality to meet our needs. Through some testing we found that we could make changes to any combination of code in the development repo and subtrees, and then use the subtree split and push commands to separate out individual subtree changes, and push them to their remote repo.</p>



<p class="wp-block-paragraph">The subtree <code class="" data-line="">split</code> command, along with the <code class="" data-line="">rejoin</code> option, will find the last split that was done for the given subtree and then search all commits since then for changes to the subtree code only, and then pull those commits out into their own separate commit(s) which can then be pushed to the subtree remote repo. Using the <code class="" data-line="">squash</code> option will take all of the commits found during the split search and combine them into a single commit vs keeping all of the commits separate. The rejoin option is what essentially creates the “checkpoints” in the repo so the split command can avoid searching the entire git history every time it is run.</p>



<p class="wp-block-paragraph">With this type of workflow we would be able to develop all of our libraries together, including creating single PRs in our development repo for review, and then pushing changes out to the subtree remote repositories as they merged in.</p>



<h2 class="wp-block-heading"><a href="#automating-the-workflow" aria-hidden="true" class="aal_anchor" id="automating-the-workflow"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a><strong>Automating the Workflow</strong></h2>



<p class="wp-block-paragraph">With the workflow figured out, the only thing left to do was to automate as much of it as possible to create a seamless development workflow. This led us to build<a href="https://github.com/apollographql/apollo-ios-dev/blob/main/.github/workflows/pr-subtree-push.yml"> a GitHub Actions workflow</a> that watches for PRs to be merged into the main branch of our development repo. When a PR merge is detected we then run the appropriate git subtree commands to check each subtree for changes, and if changes are found then split them out and push them to their remote repository.</p>



<p class="wp-block-paragraph">This automation allowed us to fully reach our goal to provide an easy and seamless development workflow for all of our libraries, while still maintaining them as separate SPM packages.</p>



<h2 class="wp-block-heading"><a href="#wrapping-up" aria-hidden="true" class="aal_anchor" id="wrapping-up"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a><strong>Wrapping Up</strong></h2>



<p class="wp-block-paragraph">Throughout this process, and some trial and error testing out git submodules and subtrees, we were able to meet the goals we set out to achieve for our project and workflow:</p>



<ul class="wp-block-list">
<li>The ability to provide more concise SPM packages for each of our features.</li>



<li>The ability to version our SPM feature packages independently if necessary.</li>



<li>Maintain an easy development workflow that allows us to develop and review everything together, but distribute separately.</li>
</ul>



<p class="wp-block-paragraph">Here is a look structure of our Git repos before implementing subtrees, and after they were implemented in the 1.6.0 release:</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="574" src="https://wp.apollographql.com/wp-content/uploads/2024/01/Git-Without-Subtrees-1024x574.png" alt="" class="wp-image-23228" srcset="https://wp.apollographql.com/wp-content/uploads/2024/01/Git-Without-Subtrees-1024x574.png 1024w, https://wp.apollographql.com/wp-content/uploads/2024/01/Git-Without-Subtrees-300x168.png 300w, https://wp.apollographql.com/wp-content/uploads/2024/01/Git-Without-Subtrees-768x431.png 768w, https://wp.apollographql.com/wp-content/uploads/2024/01/Git-Without-Subtrees-1536x861.png 1536w, https://wp.apollographql.com/wp-content/uploads/2024/01/Git-Without-Subtrees-1200x673.png 1200w, https://wp.apollographql.com/wp-content/uploads/2024/01/Git-Without-Subtrees.png 1725w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /></figure>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="886" src="https://wp.apollographql.com/wp-content/uploads/2024/01/Git-With-Subtrees-1024x886.png" alt="" class="wp-image-23230" srcset="https://wp.apollographql.com/wp-content/uploads/2024/01/Git-With-Subtrees-1024x886.png 1024w, https://wp.apollographql.com/wp-content/uploads/2024/01/Git-With-Subtrees-300x259.png 300w, https://wp.apollographql.com/wp-content/uploads/2024/01/Git-With-Subtrees-768x664.png 768w, https://wp.apollographql.com/wp-content/uploads/2024/01/Git-With-Subtrees-1536x1328.png 1536w, https://wp.apollographql.com/wp-content/uploads/2024/01/Git-With-Subtrees-1200x1038.png 1200w, https://wp.apollographql.com/wp-content/uploads/2024/01/Git-With-Subtrees-1980x1712.png 1980w, https://wp.apollographql.com/wp-content/uploads/2024/01/Git-With-Subtrees.png 1998w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /></figure>



<p class="wp-block-paragraph">This specific subtree use case meets our needs perfectly as an open-source project with multiple feature libraries, and is great for our uses because of the benefits we have described in this article. Hopefully this article can provide insight into how other projects may benefit from a subtree setup. Whether this is your first time hearing about subtrees, or you just didn’t believe they could benefit your project, there is a lot of power in the commands available through git subtrees that could be combined to achieve many different outcomes for different use cases.</p>



<p class="wp-block-paragraph"><br>We always welcome your feedback, so please don’t hesitate to reach out on<a href="https://github.com/apollographql/apollo-ios"> GitHub</a>, the<a href="https://community.apollographql.com/tag/mobile"> Apollo Community Forums</a> , or the<a href="https://discord.gg/graphos"> Apollo Discord</a> server.</p>


How Apollo Manages Swift Packages in a Monorepo with Git Subtrees


<p class="wp-block-paragraph">Nullability is a fundamental concept in many programming languages giving us the ability to express the absence of a value or assigned object. This is particularly relevant in strongly typed languages where each constant or variable must be defined with one of the language data types or explicitly allowed to be null.</p>



<p class="wp-block-paragraph">GraphQL is strongly-typed and all fields are, by default, nullable with <code class="" data-line="">null</code> being a valid response for any field unless explicitly declared otherwise. In GraphQL syntax a trailing exclamation mark is used to denote a field that uses a <a href="https://spec.graphql.org/draft/#sec-Non-Null">Non-Null</a> type, like this:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-swift" data-line="">{
  nullableField: String
  nonNullableField: String!
}</code></pre>



<p class="wp-block-paragraph">Strong typing is also one of the defining characteristics of Swift where the use of the <a href="https://developer.apple.com/documentation/swift/optional"><code class="" data-line="">Optional</code></a> type ensures that nullable (<code class="" data-line="">nil</code>) values are handled explicitly. Swift default type behavior is the opposite of GraphQL, though, and types are defined as non-null unless explicitly declared otherwise. The question mark on a type declaration indicates that the value it contains is optional (nullable), like this:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-swift" data-line="">let nonOptionalValue: String
let optionalValue: String?</code></pre>



<p class="wp-block-paragraph"><em><strong>Note: </strong>GraphQL has <a href="https://spec.graphql.org/draft/#sec-Non-Null.Nullable-vs-Optional">concepts</a> of both Nullable and Optional, and there is semantic overlap with the Swift <code class="" data-line="">&lt;a href=&quot;https://developer.apple.com/documentation/swift/optional&quot;&gt;Optional&lt;/a&gt;</code> type. It is worth taking the time to understand each to avoid confusion.</em></p>



<h2 class="wp-block-heading"><a href="#nullability-in-generated-swift" aria-hidden="true" class="aal_anchor" id="nullability-in-generated-swift"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Nullability in generated Swift</h2>



<p class="wp-block-paragraph">In the section above, we showed how nullability is an integral part of both languages. Let’s explore how nullability is used in the Swift code generated by Apollo iOS.</p>



<p class="wp-block-paragraph">During code generation when a GraphQL field type is defined as nullable, Apollo iOS will translate that into a Swift <code class="" data-line="">Optional</code> type, allowing the generated model to receive <code class="" data-line="">null</code> as a valid response for that field.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-swift" data-line="">type Query {
  allAnimals: [Animal]
}

interface Animal {
  species: String # &lt;- nullable
}

type Predator implements Animal {
  species: String # &lt;- nullable
}

type Pet implements Animal {
  species: String # &lt;- nullable
  name: String # &lt;- nullable
}</code></pre>



<pre class="wp-block-prismatic-blocks"><code class="language-swift" data-line="">query AllAnimals {
  allAnimals {
    species
  }
}</code></pre>



<pre class="wp-block-prismatic-blocks"><code class="language-swift" data-line="">class AllAnimalsQuery: GraphQLQuery {
  struct Data: SelectionSet {
    struct AllAnimal: SelectionSet {
      var species: String? { get } // &lt;- optional
    }
  }
}</code></pre>



<p class="wp-block-paragraph"><em><strong>Note: </strong>There are cases where non-nullable fields will be generated as nullable by using the <code class="" data-line="">@include</code> or <code class="" data-line="">@skip</code> directives. In these cases, the field can be returned as <code class="" data-line="">null</code> and therefore a Swift <code class="" data-line="">Optional</code> type is needed.</em></p>



<p class="wp-block-paragraph">If you’ve used Apollo iOS to generate Swift code before you might have noticed that some fragment accessors are generated as optional too. This is because the fragment’s fields might not be returned in the response depending on the object’s type.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-swift" data-line="">query AllAnimals {
  allAnimals {
    species
    ... on Pet {
      ...PetDetails
    }
  }
}

fragment PetDetails on Pet {
  name
}</code></pre>



<pre class="wp-block-prismatic-blocks"><code class="language-swift" data-line="">class AllAnimalsQuery: GraphQLQuery {
  struct Data: SelectionSet {
    struct AllAnimal: SelectionSet {
      var species: String? { get } // &lt;- optional
      var asPet?: AsPet { _asInlineFragment() } // &lt;- optional
      
      struct AsPet: InlineFragment {
        var name: String? { get } // &lt;- optional
      }
    }
  }
}</code></pre>



<h3 class="wp-block-heading"><a href="#where-is-graphqlnullable" aria-hidden="true" class="aal_anchor" id="where-is-graphqlnullable"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a><strong>Where is <code class="" data-line="">GraphQLNullable</code>?</strong></h3>



<p class="wp-block-paragraph">So far we’ve explored nullability in GraphQL and Swift, but we still haven’t encountered the <code class="" data-line="">GraphQLNullable</code> type yet. Looking at the way nullable types are defined in both languages it is reasonable to assume that they can be expressed in the same way, albeit with slightly different syntax. However, that’s not true.</p>



<p class="wp-block-paragraph">A Swift <code class="" data-line="">Optional</code> either has a value, which must be unwrapped, or there is no value. Similarly, GraphQL types either have a value or there is no value but, most importantly, <a href="https://spec.graphql.org/draft/#sec-Null-Value">null</a> values have two semantically different ways to represent the lack of a value: <em>explicitly</em> by providing the literal value: <code class="" data-line="">null</code>; <em>implicitly</em> by not providing a value at all. Trying to reconcile this difference is where <code class="" data-line="">GraphQLNullable</code> is required.</p>



<p class="wp-block-paragraph">n the same way that Swift’s <code class="" data-line="">Optional</code> type is an enum, <code class="" data-line="">GraphQLNullable</code> is also a Swift <code class="" data-line="">enum</code> providing the <code class="" data-line="">some</code> and <code class="" data-line="">none</code> cases but additionally the third possible case allowed by GraphQL &#8211; <code class="" data-line="">null</code>.</p>



<ul class="wp-block-list">
<li><code class="" data-line="">some</code> represents the presence of a value</li>



<li><code class="" data-line="">none</code> represents the <em>implicit</em> absence of a value, aka <code class="" data-line="">nil</code></li>



<li><code class="" data-line="">null</code> represents an <em>explicitly</em> null value</li>
</ul>



<p class="wp-block-paragraph"><code class="" data-line="">GraphQLNullable</code> is not needed in the generated response models though because whether a GraphQL response contains <code class="" data-line="">null</code> for a field or the field is not present, both are represented in the generated response as a Swift optional. The only time a field is allowed to be missing from a GraphQL response is as a result of the <code class="" data-line="">@include</code>, <code class="" data-line="">@skip</code> or <code class="" data-line="">@defer</code> directives. Any other time a field is missing would indicate a partial response due to a <a href="https://spec.graphql.org/draft/#sec-Errors.Field-Errors">field error</a>.</p>



<p class="wp-block-paragraph">It is only on input types where the subtle <a href="https://spec.graphql.org/draft/#sec-Null-Value">difference</a> between <code class="" data-line="">nil</code> and <code class="" data-line="">null</code> becomes important. In a mutation or input variable, an explicit <code class="" data-line="">null</code> value could be taken to represent the deletion of a field, whereas the absence of an explicit value (i.e.: <code class="" data-line="">nil</code>) could be taken to imply no change to the field. Unfortunately, some GraphQL server implementations simply treat them the same, and many developers who use GraphQL are unaware of the difference. This is also in contrast to type-safe languages which cannot discern the difference between explicit or implicit <code class="" data-line="">nil</code>.</p>



<h3 class="wp-block-heading"><a href="#but-why" aria-hidden="true" class="aal_anchor" id="but-why"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>But why?</h3>



<p class="wp-block-paragraph">Apollo iOS is a general-purpose GraphQL client and must comply with the full <a href="https://spec.graphql.org/">GraphQL specification</a>. We needed to make it clear that there is a difference, and you should be explicit in what you want. Therefore, the design of <code class="" data-line="">GraphQLNullable</code> forces the user to select a case that signals their intent without question.</p>



<p class="wp-block-paragraph"><code class="" data-line="">GraphQLNullable</code> was introduced with the major <code class="" data-line="">1.0</code> release and is, without doubt, an improvement over the previous syntax of double-optional. Developers were often confused by this syntax where an inner optional with a value of <code class="" data-line="">nil</code> combined with an outer optional value of <code class="" data-line="">some</code> would mean the GraphQL value <code class="" data-line="">null</code>, while an outmost optional of <code class="" data-line="">nil</code> would mean the absence of a value, aka. <code class="" data-line="">nil</code>. We received plenty of questions about why values were doubly wrapped in optional and it would often lead to easy mistakes in using <code class="" data-line="">nil</code> when you actually wanted <code class="" data-line="">null</code> but the compiler could never know what your intent was.</p>



<p class="wp-block-paragraph">The change to <code class="" data-line="">GraphQLNullable</code> hasn’t been without friction, though, and most of the feedback we have received is from developers who say they do not need to be concerned with the difference between <code class="" data-line="">nil</code> and <code class="" data-line="">null</code>. We believe in the value of being explicit, but it does make the usage of these fields more cumbersome because of having to use the verbose syntax of <code class="" data-line="">.some()</code> or <code class="" data-line="">GraphQLNullable()</code>, especially when combined with another <code class="" data-line="">enum</code> type such as <code class="" data-line="">GraphQLEnum</code>.</p>



<h2 class="wp-block-heading"><a href="#examples" aria-hidden="true" class="aal_anchor" id="examples"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Examples</h2>



<p class="wp-block-paragraph">Consider the following definitions:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-swift" data-line="">struct Filter {
  let species: String
  let name: String? = nil
  let predator: Bool
}

var filter: GraphQLNullable&lt;Filter&gt;

// Implicitly stating the absence of a value, aka nil.
filter = .none 

// Explicitly stating a null value
filter = .null

// Stating the presence of a value
filter = .some(.init(
  species: &quot;Canine&quot;, 
  predator: false
))</code></pre>



<p class="wp-block-paragraph">As you can see above, the <code class="" data-line="">none</code> and <code class="" data-line="">null</code> cases are easy enough to use and clear in their semantics, whereas having to wrap values in <code class="" data-line="">some</code> is awkward and less clear to someone reading the code who may be unfamiliar with <code class="" data-line="">GraphQLNullable</code>.</p>



<p class="wp-block-paragraph">For additional convenience, you&#8217;ll find that <code class="" data-line="">GraphQLNullable</code> conforms to Swift’s <code class="" data-line="">ExpressibleBy</code> protocols that match GraphQL&#8217;s scalar types, such as <code class="" data-line="">ExpressibleByStringLiteral</code>, <code class="" data-line="">ExpressibleByIntegerLiteral</code>, etc. So if your <code class="" data-line="">GraphQLNullable</code> property is wrapping a GraphQL scalar type, then initialization can be done as follows:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-swift" data-line="">let aString: GraphQLNullable&lt;String&gt; = &quot;value&quot;
let aBool: GraphQLNullable&lt;Bool&gt; = true
let aInt: GraphQLNullable&lt;Int&gt; = 123
let aDouble: GraphQLNullable&lt;Double&gt; = 1.1</code></pre>



<p class="wp-block-paragraph"><code class="" data-line="">GraphQLNullable</code> also has a convenient nil coalescing operator useful in cases where the value being evaluated is optional itself:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-swift" data-line="">let species: GraphQLNullable = optionalValue ?? .null</code></pre>



<h3 class="wp-block-heading"><a href="#improvements" aria-hidden="true" class="aal_anchor" id="improvements"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Improvements</h3>



<p class="wp-block-paragraph">Despite the conveniences, we’ve seen that the <code class="" data-line="">some</code> case is still awkward to use. For those who aren’t concerned about the semantic difference of <code class="" data-line="">nil</code> and <code class="" data-line="">null</code> there have been suggestions from the community for an extension on <code class="" data-line="">GraphQLNullable</code> that can help with the initialization of nullable values.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-swift" data-line="">extension GraphQLNullable {
  init(optionalValue value: Wrapped?) {
    if let value {
      self = .some(value)
    } else {
      self = .none // &lt;- change this to .null if your server requires
    }
  }
}</code></pre>



<p class="wp-block-paragraph"><em><strong>Note: </strong>We choose not to provide this extension by default in Apollo iOS because the decision to return <code class="" data-line="">.none</code> vs. <code class="" data-line="">.null</code> is going to be specific to how your connecting GraphQL server interprets nullable values. You should take the time to fully understand the impact of this extension and what the resultant input field value is signaling to your server.</em></p>



<h2 class="wp-block-heading"><a href="#wrapping-up" aria-hidden="true" class="aal_anchor" id="wrapping-up"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Wrapping up</h2>



<p class="wp-block-paragraph">GraphQL and Swift are a good fit. They are both strongly typed and have nullability built-in. Their syntax is quite similar even if the defaults are different and the details of handling <code class="" data-line="">null</code> vs <code class="" data-line="">nil</code> can get complicated for input values.</p>



<p class="wp-block-paragraph">I hope this article cleared up some of the confusion around <code class="" data-line="">GraphQLNullable</code> and provided you with some insight into its design.</p>



<p class="wp-block-paragraph">We welcome your feedback, and please don’t hesitate to reach out on <a href="https://github.com/apollographql/apollo-ios">GitHub</a>, the <a href="https://community.apollographql.com/tag/mobile">Apollo Community</a>, or the <a href="https://discord.gg/graphos">Apollo Discord</a> server.</p>


GraphQLNullable is not a trap!

The main title stands out brightly near the middle: "Office Hours" with the subtitle "Apollo iOS". In the top right corner, two astronauts help assemble a GraphQL logo, with an Apollo logo at the center of it.

Office Hours: Apollo iOS – 16 June 2023

Office Hours: Apollo iOS


<p class="wp-block-paragraph">As developers, we all know code generation can save us a ton of time, but can also be a pain point if the generated code needs to be refactored. When it works as expected code generation provides us with: productivity, simplification, portability, and consistency. When it doesn’t work as expected we experience consistency issues and code maintenance overhead.</p>



<p class="wp-block-paragraph">The primary challenge with code generation is many tools end up exporting unnecessarily verbose code that you have to spend hours refactoring just to get it to where you need it to be. In some cases it’s just easier to write your code from scratch instead of relying on the generated code.</p>



<p class="wp-block-paragraph">When we started to gather feedback on our now legacy <a href="https://www.apollographql.com/docs/ios/v0-legacy">Apollo iOS client</a> v.51 we realized one of the biggest pain points our users had was with the generated code being provided by the Client SDK. This was leading to a lot of rework of the generated code or in some cases having to completely throw the code out and re-write it from scratch. To add to the challenges, the previous code generation tooling was written in Typescript which isn’t native for most iOS developers who use Swift as their primary development language.</p>



<p class="wp-block-paragraph">At Apollo we strive to provide developer solutions and tooling that makes developers lives easier so you can join us on our journey to the <strong><a href="https://www.apollographql.com/blog/announcement/backend/the-supergraph-a-new-way-to-think-about-graphql/?referrer=blog">supergraph</a>.</strong> Today we are very excited to announce the new <a href="https://www.apollographql.com/docs/ios/" data-type="URL" data-id="https://www.apollographql.com/docs/ios/">Apollo iOS Client 1.0</a> which offers an entirely new approach to code generation.</p>



<p class="wp-block-paragraph"><strong>1.0 includes the following improvements:</strong></p>



<ul class="wp-block-list">
<li>Removal of all dependencies on Typescript and NPM</li>



<li>A complete rewrite of the code generation tooling in Swift</li>



<li>A greatly improved runtime performance</li>



<li>Improved syntax for the use of <a href="https://www.apollographql.com/blog/graphql/basics/using-nullability-in-graphql/">GraphQL Nullablilty</a></li>



<li>A reduction in overall generated code size and generated code complexity</li>



<li>A reduction in the overall time to generate code</li>



<li>A simpler way to construct fragment objects from the generated data objects</li>



<li>Improved data validation</li>



<li>Improved ease of use and overall flexibility</li>



<li>Improved ability to build tests around the generated models</li>



<li>Easier access to code generation &#8211; In previous versions you had to write code for your code generation configuration. Now with a simple configuration file you can get command line access to code generation.</li>
</ul>



<h3 class="wp-block-heading"><a href="#generating-code-in-apollo-ios-1-0" aria-hidden="true" class="aal_anchor" id="generating-code-in-apollo-ios-1-0"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a><strong>Generating Code in Apollo iOS 1.0</strong></h3>



<p class="wp-block-paragraph"><a href="https://www.apollographql.com/docs/ios/code-generation/introduction">Apollo iOS 1.0</a> generates operation objects for your GraphQL operations, providing a type-safe way to construct operations and provide values for input variables in your Swift code. Each generated operation contains a set of robust, strongly-typed models for its response. These generated models help you access your GraphQL response data in a type-safe and flexible format. Because generated response models are operation-specific, they include properties only for the GraphQL fields included in their corresponding operation. This means you can rely on the Swift type checker to flag data access errors at compile time.</p>



<p class="wp-block-paragraph">To generate models, Apollo iOS 1.0 requires two input sources:</p>



<ol class="wp-block-list">
<li><strong>A GraphQL Schema:</strong> which you can obtain fro your GraphQL server or from <a href="https://studio.apollographql.com/sandbox/explorer/">Apollo Studio Explorer Sandbox.</a> The schema is just a list of all of the possible queries and data types that are available to you. The schema can be thought of as a “<em>code generation contract</em>” of what it&#8217;s <em>possible</em> to ask for.</li>



<li><strong>A set of GraphQL operations and /or fragments:</strong> A GraphQL operation defines an interaction with your schema. A GraphQL operation can be a query, a mutation, or a subscription. All operations define a set of fields from the types in your schema to fetch data for. The operation definition determines what the response your GraphQL server provides will include. Your operation input sources can also include files that define <a href="https://www.apollographql.com/docs/ios/fetching/fragments">GraphQL fragments </a>These fragments can be referenced by your operation definitions.</li>
</ol>



<p class="wp-block-paragraph">The most basic way to think about this is the following equation:</p>



<p class="wp-block-paragraph"><strong>Schema + Operations = Generated Code</strong></p>



<figure class="wp-block-image size-full"><img loading="lazy" decoding="async" width="837" height="175" src="https://wp.apollographql.com/wp-content/uploads/2022/10/code-gen-equation.png" alt="" class="wp-image-16740" srcset="https://wp.apollographql.com/wp-content/uploads/2022/10/code-gen-equation.png 837w, https://wp.apollographql.com/wp-content/uploads/2022/10/code-gen-equation-300x63.png 300w, https://wp.apollographql.com/wp-content/uploads/2022/10/code-gen-equation-768x161.png 768w" sizes="auto, (max-width: 837px) 100vw, 837px" /></figure>



<p class="wp-block-paragraph">Apollo iOS combines the type information from your schema with your operation definitions to generate models. The schema provides the information needed to generate type-safe models, and your operations define the shape and structure of the generated models.</p>



<p class="wp-block-paragraph">The Apollo iOS Code Generation Engine parses your schema and operations and ensures that your operations are valid to be performed against the schema provided. It generates models that include all of the necessary information to create type-safe operations, send those operations as network requests, and parse the response data onto the type-safe response models.</p>



<h3 class="wp-block-heading"><a href="#generated-code-operations" aria-hidden="true" class="aal_anchor" id="generated-code-operations"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a><strong>Generated Code: Operations</strong></h3>



<p class="wp-block-paragraph">For example, given the following schema:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-graphql" data-line="">type Query {
  hero: Character!
}
interface Character {
  id: String!
  name: String!
  friends: [Character!]
  appearsIn: [Episode]!
 }
 type Human implements Character {
   id: String!
   name: String!
   friends: [Character]
   appearsIn: [Episode]!
   height(unit: LengthUnit = METER): Float
 }
 type Droid implements Character {
   id: String!
   name: String!
   friends: [Character]
   appearsIn: [Episode]!
   primaryFunction: String
}</code></pre>



<p class="wp-block-paragraph">And the following query:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-graphql" data-line="">query HeroAndFriendsNames {
  hero {
  name
   friends {
      id
      name
    }
  }
}</code></pre>



<p class="wp-block-paragraph">Apollo iOS generates a type-safe model that looks something like this (details are omitted to focus on the class structure):</p>



<pre class="wp-block-prismatic-blocks"><code class="language-swift" data-line="">class HeroAndFriendsNamesQuery: GraphQLQuery {
  struct Data: SelectionSet {
    let hero: Hero

    struct Hero: SelectionSet {
      let id: String
      let name: String
      let friends: [Friend]?

      struct Friend: SelectionSet {
        let id: String
        let name: String
      }
    }
  }
}</code></pre>



<p class="wp-block-paragraph">Because the <code class="" data-line="">HeroAndFriendsNames</code> query doesn&#8217;t fetch <code class="" data-line="">appearsIn</code>, this property is not part of the returned result type and cannot be accessed here. Similarly, <code class="" data-line="">id</code> is only accessible in <code class="" data-line="">Friend</code>, not in <code class="" data-line="">Hero</code>.</p>



<p class="wp-block-paragraph">Because GraphQL supports nullability, you have compile-time type safety. If the request is successful, all queried data (and only this data) will be accessible. There is no need to handle null fields in UI code.</p>



<h3 class="wp-block-heading"><a href="#generated-code-fragments" aria-hidden="true" class="aal_anchor" id="generated-code-fragments"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a><strong>Generated Code: Fragments</strong></h3>



<p class="wp-block-paragraph">A named fragment is defined in a <code class="" data-line="">.graphql</code> file, just like an operation definition. A named fragment always has a name and a &#8220;parent type&#8221;, that is, the type in the schema that it can be applied to. This fragment can be included in a selection set in an operation definition.</p>



<p class="wp-block-paragraph">Apollo iOS generates separate result types for named fragments, which means they are a great way of keeping UI components or utility functions independent of specific queries.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-graphql" data-line="">fragment HeroDetails on Character {
  name
  appearsIn
}</code></pre>



<pre class="wp-block-prismatic-blocks"><code class="language-graphql" data-line="">query HeroAndFriends {
  hero {
    name
    ...HeroDetails
    friends {
      ...HeroDetails
    }
  }
}</code></pre>



<p class="wp-block-paragraph">Apollo iOS generates a type-safe model for the <code class="" data-line="">HeroDetails</code> fragment that looks like this (details are omitted to focus on the class structure):</p>



<pre class="wp-block-prismatic-blocks"><code class="language-swift" data-line="">struct HeroDetails: MySchema.SelectionSet, Fragment {
  let name: String
  let appearsIn: [Episode]
}</code></pre>



<p class="wp-block-paragraph">The result data models generated for the <code class="" data-line="">HeroAndFriendsQuery</code> will include the fields from the <code class="" data-line="">HeroDetails</code> fragment and are able to be converted into the <code class="" data-line="">HeroDetails</code> fragment model.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-swift" data-line="">class HeroAndFriendsQuery: GraphQLQuery {
  struct Data: SelectionSet {
    let hero: Hero

    struct Hero: SelectionSet {
      let name: String
      let friends: [Friend]
      let appearsIn: [Episode]

      // Fragment Conversion Declaration
      var fragments: Fragments
      struct Fragments {
        var heroDetails: HeroDetails { ... }
      }

      struct Friend: SelectionSet {
        let name: String
        let appearsIn: [Episode]

        // Fragment Conversion Declaration
        var fragments: Fragments
        struct Fragments {
          var heroDetails: HeroDetails { ... }
        }
      }
    }
  }
}</code></pre>



<h3 class="wp-block-heading"><a href="#the-codegen-cli" aria-hidden="true" class="aal_anchor" id="the-codegen-cli"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>The Codegen CLI</h3>



<p class="wp-block-paragraph">The new <a href="https://www.apollographql.com/docs/ios/code-generation/codegen-cli">Codegen CLI </a>provides a command line tool that streamlines the process of running code generation. The CLI can be ran manually from the Terminal (or any other shell program) or can be called into from bash scripts. The CLI is a powerful tool that comes out of the box with our new iOS client 1.0</p>



<p class="wp-block-paragraph"><strong>The Codegen CLI has three primary commands:</strong></p>



<ul class="wp-block-list">
<li><strong>Initialize</strong>: Initializes an <code class="" data-line="">apollo-codegen-configuration.json</code> file that can be used to configure how the CLI generates code.</li>



<li><strong>Fetch Schema</strong>: Fetches your GraphQL schema and writes it to a file. The schema is required in order to run code generation.</li>



<li><strong>Generate:</strong> Runs the code generation engine using the configuration in your <code class="" data-line="">apollo-codegen-configuration.json</code> file.</li>
</ul>



<h3 class="wp-block-heading"><a href="#conclusion" aria-hidden="true" class="aal_anchor" id="conclusion"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a><strong>Conclusion</strong></h3>



<p class="wp-block-paragraph">This blog highlights just some of the great new features of the new Apollo iOS Client 1.0 and we invite you to read the complete <a href="https://www.apollographql.com/docs/ios/" data-type="URL" data-id="https://www.apollographql.com/docs/ios/">iOS 1.0 documentation</a> for more details! If you are using our current<a href="https://www.apollographql.com/docs/ios/v0-legacy"> Legacy 0.X version</a> of the Apollo iOS client we invite you to upgrade to 1.0 soon. Please note, that all existing features of 0.x are still fully supported in 1.0.</p>



<p class="wp-block-paragraph">Finally, we welcome all feedback and input you might have so please let us know what you think in the <a href="https://github.com/apollographql/apollo-ios">Apollo iOS Client Github Repository</a>.</p>


Mobile

Mastering Cache Key Resolution in Apollo iOS with @typePolicy and @fieldPolicy

New GraphQL courses for iOS and Android development

How Apollo Manages Swift Packages in a Monorepo with Git Subtrees

GraphQLNullable is not a trap!

Office Hours: Apollo iOS – 16 June 2023

Office Hours: Apollo iOS

Apollo iOS Client 1.0 with improved code generation

Past posts

Mapping GraphQL types to Swift

Mobile

Mastering Cache Key Resolution in Apollo iOS with @typePolicy and @fieldPolicy

New GraphQL courses for iOS and Android development

How Apollo Manages Swift Packages in a Monorepo with Git Subtrees

GraphQLNullable is not a trap!

Office Hours: Apollo iOS – 16 June 2023

Office Hours: Apollo iOS

Apollo iOS Client 1.0 with improved code generation

Past posts

Mapping GraphQL types to Swift

Stay in our orbit