Enhance customer experiences with Apollo GraphOS


<p>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>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>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>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>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>GraphQL, the <em>lingua franca</em> of APIs, offers a palette of expressive tools: interfaces, nullability, deprecation, unions, etc.</p>



<p>Occasionally though, a backend’s contract would be reflected more precisely, if only it could be represented in the schema. Take unions for example: they can be used for output types, but not input types, so a search API accepting different kinds of criteria can be implemented like this:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-graphql">type Query {
  searchByName(name: String!): User
  searchById(id: ID!): User
  searchBy...
}</code></pre>



<p>This works, but is a bit tedious, and what we <em>really</em> mean is something like <code>search(name: String! | id: ID! | …)</code>. What can we do to improve the situation?<br>GraphQL is an open standard, with a working group and <a href="https://github.com/graphql/graphql-spec/blob/main/CONTRIBUTING.md">processes</a> in place to support its evolution: the RFCs (requests for comments).</p>



<h2 class="wp-block-heading"><a href="#the-oneof-rfc" aria-hidden="true" class="aal_anchor" id="the-oneof-rfc"><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 OneOf RFC</h2>



<p>Seeing this possible room for improvement, the GraphQL community came up with <a href="https://github.com/graphql/graphql-spec/pull/825">this RFC</a>, which proposes a new built-in directive: <code>@oneOf</code>. It can be applied to input types to indicate that one and only <strong>one of</strong> the fields must be provided.</p>



<p>In our example above, we can take advantage of it like this:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-graphql">type Query {
  search(criteria: SearchCriteria!): User
}

input SearchCriteria @oneOf {
  name: String
  id: ID
  #...
}
</code></pre>



<p>With that, a client can query <code>search({ name: “John” })</code> or <code>search({ id: “42” })</code> but <code>search({ name: “John”, id: “42” })</code> would result in a validation error.<br></p>



<p><strong>Backwards compatibility</strong></p>



<p>A nice property of the proposal is that it doesn’t introduce any new syntax and therefore should be transparent for any client libraries that have no knowledge of the new directive.</p>



<p>If you provide more than one field to a OneOf input type, a “OneOf aware” library will warn you early, before executing the operation. An older library will treat the input type as a regular one, and will allow its execution, but the <strong>backend</strong> will then provide an error, as expected.<br>To achieve this compatibility, all the fields of a OneOf input type must be declared as if they were <strong>nullable</strong> (without an exclamation mark).</p>



<pre class="wp-block-prismatic-blocks"><code class="language-graphql">input SearchCriteria @oneOf {
  name: String
  id: ID! # Illegal!
  type: Type! # Illegal!
}</code></pre>



<p>Without that requirement, pre-OneOf client libraries would require to provide <strong>all</strong> non-nullable fields &#8211; which wouldn’t make sense since only <strong>one</strong> field must be provided.</p>



<p>Note: although the fields are declared in the schema as nullable, passing the value null is not allowed. This may seem counterintuitive at first but the reason lies within GraphQL’s type system &#8211; <a href="https://github.com/graphql/graphql-spec/pull/825#issuecomment-1835978233">this RFC comment</a> explains it all.</p>



<h2 class="wp-block-heading"><a href="#support-in-apollo-kotlin" aria-hidden="true" class="aal_anchor" id="support-in-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>Support in Apollo Kotlin</h2>



<p>If you are an Apollo Kotlin user and want to try @oneOf today, you’re in luck! We’ve added experimental support for it in <a href="https://www.apollographql.com/blog/apollo-kotlin-4-is-now-available">version 4</a>:</p>



<ul class="wp-block-list">
<li><a href="https://www.apollographql.com/docs/kotlin/advanced/plugin-recipes#downloading-a-schema">Fetching a schema</a> via introspection on a OneOf-aware server will include the <code>@oneOf</code> directives.</li>
</ul>



<ul class="wp-block-list">
<li>You’ll get a runtime error if you build a oneOf input type and provide more than one field:</li>
</ul>



<pre class="wp-block-prismatic-blocks"><code class="language-kotlin">SearchCriteria.Builder()
  .name(&quot;Luke&quot;)
  .id(&quot;42&quot;)
  .build() // Throws! Must provide only one field.</code></pre>



<ul class="wp-block-list">
<li>When using&nbsp;<a href="https://www.apollographql.com/docs/kotlin/testing/android-studio-plugin/">the IDE plugin</a> you’ll get errors in the editor:</li>
</ul>



<figure class="wp-block-image size-full"><img loading="lazy" decoding="async" width="926" height="232" src="https://wp.apollographql.com/wp-content/uploads/2024/09/Screenshot-2024-09-23-at-14.48.01.png" alt="In Kotlin" class="wp-image-23879" srcset="https://wp.apollographql.com/wp-content/uploads/2024/09/Screenshot-2024-09-23-at-14.48.01.png 926w, https://wp.apollographql.com/wp-content/uploads/2024/09/Screenshot-2024-09-23-at-14.48.01-300x75.png 300w, https://wp.apollographql.com/wp-content/uploads/2024/09/Screenshot-2024-09-23-at-14.48.01-768x192.png 768w" sizes="auto, (max-width: 926px) 100vw, 926px" /></figure>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="180" src="https://wp.apollographql.com/wp-content/uploads/2024/09/Screenshot-2024-09-23-at-16.59.59-1024x180.png" alt="In GraphQL" class="wp-image-23881" srcset="https://wp.apollographql.com/wp-content/uploads/2024/09/Screenshot-2024-09-23-at-16.59.59-1024x180.png 1024w, https://wp.apollographql.com/wp-content/uploads/2024/09/Screenshot-2024-09-23-at-16.59.59-300x53.png 300w, https://wp.apollographql.com/wp-content/uploads/2024/09/Screenshot-2024-09-23-at-16.59.59-768x135.png 768w, https://wp.apollographql.com/wp-content/uploads/2024/09/Screenshot-2024-09-23-at-16.59.59-1200x211.png 1200w, https://wp.apollographql.com/wp-content/uploads/2024/09/Screenshot-2024-09-23-at-16.59.59.png 1322w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /></figure>



<h2 class="wp-block-heading"><a href="#support-in-apollo-server" aria-hidden="true" class="aal_anchor" id="support-in-apollo-server"><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>Support in Apollo Server</h2>



<p>With <a href="https://github.com/apollographql/apollo-server" data-type="link" data-id="https://github.com/apollographql/apollo-server">Apollo Server</a>, you can use <code>@oneOf</code> in your schemas starting from version 4.</p>



<h2 class="wp-block-heading"><a href="#whats-next" aria-hidden="true" class="aal_anchor" id="whats-next"><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>What’s next?</h2>



<p>The GraphQL RFC process is an iterative one. The OneOf RFC is currently in Stage 2 (“Draft”), which <a href="https://github.com/graphql/graphql-spec/blob/main/CONTRIBUTING.md#stage-2-draft">means</a> it is thought to be ready to be accepted into the specification but awaiting feedback from the community. Try it today with Apollo Kotlin and Apollo Server, and make your voice heard on <a href="https://github.com/graphql/graphql-spec/pull/825">the ticket</a> and in the Apollo <a href="https://github.com/apollographql/apollo-kotlin/issues">issue</a> <a href="https://github.com/apollographql/apollo-server/issues">trackers</a>.</p>


More expressive schemas with @oneOf


<p>Apollo Kotlin is now built with K2, the new compiler that has recently been released with Kotlin 2. Here are a few details on the migration process.</p>



<h2 class="wp-block-heading"><a href="#what-is-k2" aria-hidden="true" class="aal_anchor" id="what-is-k2"><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>What is K2?</strong></h2>



<p>K2 is a complete rewrite of the Kotlin compiler frontend, « <em>the part of the compiler that parses your code and performs the semantic analysis, data flow analysis, call resolution, and type inference »</em> (<a href="https://blog.jetbrains.com/kotlin/2023/02/k2-kotlin-2-0/">source</a>). The result is a faster, more robust and reliable compiler that should also be easier to evolve in the future.</p>



<h2 class="wp-block-heading"><a href="#switching-to-k2-in-apollo-kotlin" aria-hidden="true" class="aal_anchor" id="switching-to-k2-in-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><strong>Switching to K2 in Apollo Kotlin</strong></h2>



<p>On Apollo Kotlin, we started looking at K2 early on, so we could be ready when it’s stable. A nice practice that helps catching issues early is to set up <a href="https://slack.engineering/shadow-jobs/">shadow jobs</a> &#8211; in our case though that wasn’t practical, since it took a while before we could reach a state where the project would build. Instead we just maintained the necessary changes in a <a href="https://github.com/apollographql/apollo-kotlin/tree/keep-k2">dedicated branch</a> in parallel to our main one. Towards the end, we merged all non-breaking changes to the main branch, so as to keep the diff minimal.</p>



<p>In a perfect world, using one compiler or another should have no impact for a precisely specified language. In reality though, while this should be the case for most projects, the chances of stumbling upon behavior differences increase with the project size.</p>



<p>In practice, when switching the project to K2, we got compilation errors that needed tweaks in our code. This could be due to constructs that were allowed in K1 but shouldn’t have been and that K2 had fixed. Sometimes they were just small differences in the way the language could be used. We’ve also seen a few actual bugs in the new compiler.</p>



<p>This process &#8211; an iterative task with each beta and rc release &#8211; took a while and we’ve been blocked a few times, but in the end, the transition has been smooth overall. For the curious, a list of the few misc issues we’ve hit is available <a href="https://gist.github.com/BoD/29ff99fb695a3ce5e82b28159cdc5268">here</a>. These were all fixed or had workarounds in the stable release of Kotlin 2.</p>



<p>On the Compose side, one notable change with Kotlin 2 is that the Compose compiler now resides <a href="https://github.com/JetBrains/kotlin/tree/master/plugins/compose">in the Kotlin repository</a>. This should help homogenize the release cycles and version numbers between Kotlin and the Compose compiler. A <a href="https://developer.android.com/develop/ui/compose/compiler">dedicated Gradle plugin</a> is now available, which automatically imports the right version whereas this used to be a manual configuration.</p>



<h2 class="wp-block-heading"><a href="#build-performance" aria-hidden="true" class="aal_anchor" id="build-performance"><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>Build performance</strong></h2>



<p>The main promise of K2 is improved build speeds. We’re happy to report that we’ve noticed some improvement when building the whole library:</p>



<ul class="wp-block-list">
<li>with K1: <strong>1 minute 40 seconds</strong></li>



<li>with K2: <strong>1 minute</strong></li>
</ul>



<p><em>(Measured by running time </em><em>./gradlew &#8211;no-build-cache &#8211;rerun-tasks publishToMavenLocal</em><em> on a 2021 MacBook Pro with a 10 core M1 Max chip).</em></p>



<p>That’s a <strong>40%</strong> improvement!</p>



<p>If we look at build scans (<a href="https://ge.apollographql.com/s/qc442j4pu6uvq/timeline?view=by-type">K1</a>, <a href="https://ge.apollographql.com/s/co2mdwfrfh6pw/timeline?view=by-type">K2</a>), we can see that most of the time is spent in the various compilation tasks, Native being the most time consuming. The JS compilation is where most improvement is achieved.</p>



<figure class="wp-block-table"><table><tbody><tr><td><strong>Task Type</strong></td><td><strong>Duration (K1)</strong></td><td><strong>Duration (K2)</strong></td><td><strong>Improvement</strong></td></tr><tr><td>KotlinNativeCompile</td><td>1m 33s</td><td>1m 10s</td><td>25%</td></tr><tr><td>KotlinCompile (JVM)</td><td>26s</td><td>18s</td><td>30%</td></tr><tr><td>Kotlin2JsCompile</td><td>14s</td><td>8s</td><td>42%</td></tr><tr><td>KotlinCompileCommon (Metadata)</td><td>5s</td><td>3s</td><td>40%</td></tr></tbody></table></figure>



<p><em>(Parallelization disabled for a better understanding of time spent per task.)</em></p>



<h2 class="wp-block-heading"><a href="#compatibility" aria-hidden="true" class="aal_anchor" id="compatibility"><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>Compatibility</strong></h2>



<p>On Android and the JVM, the Kotlin compiler has <a href="https://kotlinlang.org/docs/kotlin-evolution.html#evolving-the-binary-format">N+1 forward compatibility</a>. The documentation states it is a best effort but in our experience, it has always worked. So a library compiled with K2 and languageVersion of 2.0 (such as Apollo Kotlin 4, coming soon!) can be used on projects using Kotlin 1.9+.</p>



<p>For native <a href="https://github.com/apollographql/apollo-kotlin/issues/5801">and JS</a>, where the ecosystem is still moving fast, that level of forward compatibility is not there yet, so Kotlin 2 is needed.</p>



<p>(A discussion about this can be seen in <a href="https://github.com/apollographql/apollo-kotlin/issues/5856">this issue</a>).</p>



<h2 class="wp-block-heading"><a href="#whats-next" aria-hidden="true" class="aal_anchor" id="whats-next"><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>What’s next?</strong></h2>



<p>The <strong>Kotlin Symbol Processing</strong> tool (KSP) has a <a href="https://github.com/google/ksp/blob/main/docs/ksp2.md">version 2</a> specifically tailored to work with K2. At the time of writing, we’re hitting <a href="https://github.com/google/ksp/issues/1823">an issue</a> that prevents us from making the switch just yet.</p>



<p>For its refactoring, inspection and navigation features, the <a href="https://www.apollographql.com/docs/kotlin/v4/testing/android-studio-plugin"><strong>Apollo IDE plugin</strong></a> interacts with the Kotlin IDE plugin, which currently uses K1 under the hood. New <a href="https://blog.jetbrains.com/idea/2024/03/k2-kotlin-mode-alpha-in-intellij-idea/">APIs based on K2</a> are coming, and we’ll update our plugin code to use them when it is time.</p>



<p>Finally, one goal of K2 has been to ease the evolution of the language. A few <strong>future language features</strong> have been announced: <a href="https://github.com/Kotlin/KEEP/blob/guards/proposals/guards.md">Guards</a>, <a href="https://github.com/Kotlin/KEEP/issues/379">Context sensitive resolution</a>, <a href="https://github.com/Kotlin/KEEP/blob/explicit-backing-fields-re/proposals/explicit-backing-fields.md">Explicit backing fields</a>, <a href="https://youtrack.jetbrains.com/issue/KT-15471">Data arguments</a>, <a href="https://youtrack.jetbrains.com/issue/KT-68296">Union types for errors</a>. We’ll keep an eye on them!</p>



<h2 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></h2>



<p>Switching to the new K2 compiler in Apollo Kotlin has been an interesting journey, which has brought improvements to our build performance.</p>



<p>We recommend <a href="https://kotlinlang.org/docs/k2-compiler-migration-guide.html">upgrading</a> your own project to benefit from enhancements and to stay in line with future developments.</p>



<p>As always, feedback is welcome &#8211; don’t hesitate to reach out on <a href="https://github.com/apollographql/apollo-kotlin">GitHub</a>, the <a href="https://discord.gg/graphos">Apollo Community</a>, or the <a href="https://slack.kotl.in/">Kotlin Slack</a>!</p>


Journey to K2: using the New Compiler in Apollo Kotlin


<p>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>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>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>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>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>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>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>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>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>The subtree <code>split</code> command, along with the <code>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>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>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>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>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>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>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>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><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>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>GraphQL is strongly-typed and all fields are, by default, nullable with <code>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">{
  nullableField: String
  nonNullableField: String!
}</code></pre>



<p>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>Optional</code></a> type ensures that nullable (<code>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">let nonOptionalValue: String
let optionalValue: String?</code></pre>



<p><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>&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>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>During code generation when a GraphQL field type is defined as nullable, Apollo iOS will translate that into a Swift <code>Optional</code> type, allowing the generated model to receive <code>null</code> as a valid response for that field.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-swift">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">query AllAnimals {
  allAnimals {
    species
  }
}</code></pre>



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



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



<p>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">query AllAnimals {
  allAnimals {
    species
    ... on Pet {
      ...PetDetails
    }
  }
}

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



<pre class="wp-block-prismatic-blocks"><code class="language-swift">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>GraphQLNullable</code>?</strong></h3>



<p>So far we’ve explored nullability in GraphQL and Swift, but we still haven’t encountered the <code>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>A Swift <code>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>null</code>; <em>implicitly</em> by not providing a value at all. Trying to reconcile this difference is where <code>GraphQLNullable</code> is required.</p>



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



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



<li><code>none</code> represents the <em>implicit</em> absence of a value, aka <code>nil</code></li>



<li><code>null</code> represents an <em>explicitly</em> null value</li>
</ul>



<p><code>GraphQLNullable</code> is not needed in the generated response models though because whether a GraphQL response contains <code>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>@include</code>, <code>@skip</code> or <code>@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>It is only on input types where the subtle <a href="https://spec.graphql.org/draft/#sec-Null-Value">difference</a> between <code>nil</code> and <code>null</code> becomes important. In a mutation or input variable, an explicit <code>null</code> value could be taken to represent the deletion of a field, whereas the absence of an explicit value (i.e.: <code>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>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>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>GraphQLNullable</code> forces the user to select a case that signals their intent without question.</p>



<p><code>GraphQLNullable</code> was introduced with the major <code>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>nil</code> combined with an outer optional value of <code>some</code> would mean the GraphQL value <code>null</code>, while an outmost optional of <code>nil</code> would mean the absence of a value, aka. <code>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>nil</code> when you actually wanted <code>null</code> but the compiler could never know what your intent was.</p>



<p>The change to <code>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>nil</code> and <code>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>.some()</code> or <code>GraphQLNullable()</code>, especially when combined with another <code>enum</code> type such as <code>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>Consider the following definitions:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-swift">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>As you can see above, the <code>none</code> and <code>null</code> cases are easy enough to use and clear in their semantics, whereas having to wrap values in <code>some</code> is awkward and less clear to someone reading the code who may be unfamiliar with <code>GraphQLNullable</code>.</p>



<p>For additional convenience, you&#8217;ll find that <code>GraphQLNullable</code> conforms to Swift’s <code>ExpressibleBy</code> protocols that match GraphQL&#8217;s scalar types, such as <code>ExpressibleByStringLiteral</code>, <code>ExpressibleByIntegerLiteral</code>, etc. So if your <code>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">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><code>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">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>Despite the conveniences, we’ve seen that the <code>some</code> case is still awkward to use. For those who aren’t concerned about the semantic difference of <code>nil</code> and <code>null</code> there have been suggestions from the community for an extension on <code>GraphQLNullable</code> that can help with the initialization of nullable values.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-swift">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><em><strong>Note: </strong>We choose not to provide this extension by default in Apollo iOS because the decision to return <code>.none</code> vs. <code>.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>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>null</code> vs <code>nil</code> can get complicated for input values.</p>



<p>I hope this article cleared up some of the confusion around <code>GraphQLNullable</code> and provided you with some insight into its design.</p>



<p>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!

How Apollo Kotlin leverages Gradle Enterprise to Rev Up Build Times


<p>We’re happy to introduce an <a href="https://github.com/apollographql/apollo-kotlin">Apollo Kotlin</a> plugin for Android Studio and IntelliJ IDEA, to help you work with the library and improve your productivity.</p>



<p>This preview release can be tried out today.</p>



<h2 class="wp-block-heading"><a href="#features" aria-hidden="true" class="aal_anchor" id="features"><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>Features</h2>



<h3 class="wp-block-heading"><a href="#on-the-fly-code-generation" aria-hidden="true" class="aal_anchor" id="on-the-fly-code-generation"><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>On-the-fly code generation</h3>



<p>Apollo Kotlin is a strongly-typed client library that generates models from your GraphQL queries. This works thanks to a Gradle plugin that triggers the code generation at build time. Normally, after touching a graphql file, to be able to use the up-to-date generated models in your Kotlin code, you would need to manually run the codegen Gradle task.</p>



<p>With the IDE plugin, this is done automatically: the codegen is run in the background whenever you touch your GraphQL queries, so you can use the models immediately.</p>



<figure class="wp-block-video"><video controls src="https://wp.apollographql.com/wp-content/uploads/2023/06/00-on-the-fly-codegen.mov"></video><figcaption class="wp-element-caption">On-the-fly code generation</figcaption></figure>



<h3 class="wp-block-heading"><a href="#migration-helpers" aria-hidden="true" class="aal_anchor" id="migration-helpers"><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>Migration helpers</h3>



<p>Apollo Kotlin 3 was a major version that introduced quite a few changes compared to version 2. While some of <a href="https://www.apollographql.com/docs/kotlin/migration/3.0/">these changes</a> require manual tweaks to the code, a lot of these can be automated. Which is what the “Migrate to Apollo Kotlin 3” action does. If you are still on version 2, now is a good time to migrate!</p>



<figure class="wp-block-video"><video controls src="https://wp.apollographql.com/wp-content/uploads/2023/06/01-migration-apollo2-to-3.mp4"></video><figcaption class="wp-element-caption">Migrate to Apollo Kotlin 3</figcaption></figure>



<p>If you are using Apollo Kotlin 3 with <a href="https://www.apollographql.com/docs/kotlin/migration/3.0/#codegen">the <code>compat</code> codegen</a>, which was meant to ease the migration from version 2 (and will be discontinued in the upcoming version 4 release), the plugin can also help with this: “Migrate to <code>operationBased</code> Codegen”.</p>



<figure class="wp-block-video"><video controls src="https://wp.apollographql.com/wp-content/uploads/2023/06/02-migration-compat-to-operationbased.mov"></video><figcaption class="wp-element-caption">Migrate to operationBased codegen</figcaption></figure>



<h3 class="wp-block-heading"><a href="#navigation" aria-hidden="true" class="aal_anchor" id="navigation"><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>Navigation</h3>



<p>When editing Kotlin code that references GraphQL queries, it is often useful to go to their definition &#8211; for instance, if you need to add a field to the selection. The natural way to do that in Android Studio is to <code>Cmd/Ctrl + click</code> (or <code>Cmd/Ctrl + b</code> on the keyboard) on the symbol. However without any special knowledge of Apollo Kotlin or GraphQL, this would go to the generated code, which is not as useful. Not anymore! The plugin adds target to go to the GraphQL definition:</p>



<figure class="wp-block-video"><video controls src="https://wp.apollographql.com/wp-content/uploads/2023/06/03-go-to-declaration.mov"></video><figcaption class="wp-element-caption">Go to GraphQL definition</figcaption></figure>



<p>Note that the generated code destination is still there, as it is sometimes handy to have a look at it.</p>



<p>We’ve also added these nifty GraphQL icons in the gutter next to operation and fragment references. Click on them to go to the definition.</p>



<p>To go to the Schema instead, use “Go To Type Declaration” (<code>Cmd/Ctrl + Shift + click</code>, or <code>Cmd/Ctrl + Shift + b</code>):</p>



<figure class="wp-block-video"><video controls src="https://wp.apollographql.com/wp-content/uploads/2023/06/04-go-to-type-declaration.mov"></video><figcaption class="wp-element-caption">Go to the schema</figcaption></figure>



<p>The reverse works too if you need it: “Find Usages” on your GraphQL operation will list Kotlin files referencing them:</p>



<figure class="wp-block-video"><video controls src="https://wp.apollographql.com/wp-content/uploads/2023/06/05-find-usages.mov"></video><figcaption class="wp-element-caption">Find code usages</figcaption></figure>



<p>We hope to add “Find Usages” on fields as well in the future.</p>



<h3 class="wp-block-heading"><a href="#more-to-come" aria-hidden="true" class="aal_anchor" id="more-to-come"><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>More to come</h3>



<p>We are working on adding more features and your ideas are very welcome! Please don’t hesitate to submit feature requests on <a href="https://github.com/apollographql/apollo-kotlin/issues/new/choose">the issue tracker</a>.</p>



<h2 class="wp-block-heading"><a href="#try-it-out" aria-hidden="true" class="aal_anchor" id="try-it-out"><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>Try it out!</h2>



<p>To install the plugin:</p>



<ol class="wp-block-list">
<li>During the preview phase, you will need to add a dedicated plugin repository:<br><br>&#8211; <code>Settings</code> &gt; <code>Plugins</code> &gt; <code>⚙️</code> &gt; <code>Manage Plugin Repositories</code> &gt; <code>➕</code> &gt; <code>https://plugins.jetbrains.com/plugins/preview/20645</code><br><br>&#8211; If you want the cutting edge, use this “snapshots” URL instead (new versions once a week): <code>https://raw.githubusercontent.com/apollographql/apollo-kotlin/main/intellij-plugin/snapshots/plugins.xml</code></li>



<li><code>Marketplace</code> &gt; Search for &#8220;Apollo GraphQL&#8221; &gt; <code>Install</code></li>
</ol>



<p>Detailed instructions are available <a href="https://github.com/apollographql/apollo-kotlin/tree/main/intellij-plugin">here</a>.</p>



<h2 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>Conclusion</h2>



<p>We hope this plugin will make your experience with Apollo Kotlin a delightful one and will help you build great apps. Stay tuned for more, and as always, your feedback is welcome! You can reach out on <a href="https://github.com/apollographql/apollo-kotlin">GitHub</a>, the <a href="https://discord.gg/graphos">Apollo Community</a>, or the <a href="https://slack.kotl.in/">Kotlin Slack</a>!</p>


Announcing the Apollo Kotlin plugin for Android Studio and IntelliJ IDEA

Line drawing of a space shuttle, the Apollo lettermark, and the text: Community Update: Apollo Client, Apollo iOS, and Apollo Kotlin

Community Update: Apollo Client, Apollo iOS, and Apollo Kotlin


<p>The concept of <code>null</code> is sometimes called a “<a href="https://en.wikipedia.org/wiki/Null_pointer#History">billion dollar mistake</a>”. Mistake or not, <code>null</code> is here to stay and there are ways to coexist peacefully!</p>



<p>In fact, nullability is one of the <a href="https://graphql.org/learn/schema/#object-types-and-fields">key features of GraphQL</a>, allowing API authors to clearly specify which fields of a type are nullable.</p>



<p>As for Kotlin, the language <a href="https://kotlinlang.org/docs/null-safety.html">supports nullability in its type system</a>, significantly reducing the risk for errors &#8211; for example assigning a potentially <code>null</code> value to a non-nullable field won’t even compile!</p>



<p>At the intersection of these two worlds lies <a href="https://github.com/apollographql/apollo-kotlin">Apollo Kotlin</a>, the GraphQL typesafe client library for Kotlin. Let’s look at a few ways the library deals with nullability.</p>



<h2 class="wp-block-heading"><a href="#null-safety-on-fields" aria-hidden="true" class="aal_anchor" id="null-safety-on-fields"><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>Null safety on fields</h2>



<p>Apollo Kotlin generates models based on your project’s GraphQL operations and the type information found in the schema. When selecting a field whose type is nullable in the schema, the corresponding field in the generated Kotlin model will also be nullable.</p>



<p>💡 By the way, notice how the GraphQL and Kotlin syntaxes are quite similar, but an important difference is how the default in GraphQL (no <code>!</code>) means nullable, whereas the default in Kotlin (no <code>?</code>) means <strong>non-nullable</strong>.</p>



<p>Schema:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-graphql">type Query {
  person(id: ID!): Person  # ← nullable
}

type Person {
  id: ID!  # ← non-nullable
  email: String  # ← nullable
}</code></pre>



<p>Query:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-graphql">query GetPersonById(id: ID!) {
  person(id: $id) {
    id
    email
  }
}</code></pre>



<p>Generated models:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-kotlin">data class Data(
  val person: Person?,  // ← nullable
)

data class Person(
  val id: String,  // ← non-nullable
  val email: String?,  // ← nullable
)</code></pre>



<p></p>



<p>There are cases where non-nullable fields will still be generated as nullable, can you guess which?</p>



<p>That’s right (you guessed!): when using the <code>@include</code> or <code>@skip</code> directives which control whether a field (or fragment) will be returned by the server. In that case the field will be <code>null</code> when not present.</p>



<p></p>



<p><strong>What about fragments?</strong></p>



<p>With the <code>operationBased</code> codegen (<a href="https://www.apollographql.com/docs/kotlin/advanced/response-based-codegen/">the default</a>), one field is generated for each fragment spread and inline fragment. When polymorphism is involved, the fragment’s fields may or may not be returned, depending on the object’s type. That is why, here too, the fragment field will be nullable &#8211; if necessary.</p>



<p>Schema:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-graphql">interface SearchResult {
  rank: Int!
}

type ProjectSearchResult implements SearchResult  {
  project: Project!
  rank: Int!
}

type UserSearchResult implements SearchResult  {
  user: User!
  rank: Int!
}</code></pre>



<p>Query:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-graphql">query Search(q: String!) {
  search {
    ... on SearchResult { rank }
    ... on ProjectSearchResult { project { name } }
    ... on UserSearchResult { user { email } }
  }
}</code></pre>



<p>Generated models:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-kotlin">data class Search(
  val onSearchResult: OnSearchResult,
  val onProjectSearchResult: OnProjectSearchResult?,  // ← nullable
  val onUserSearchResult: OnProjectSearchResult?,  // ← nullable
)</code></pre>



<p>👀 Notice <code>onSearchResult</code> is generated non-nullable. The code generator figures out that the type condition “on SearchResult” is always true for <code>search</code>, so these fields will always be present in the response &#8211; hence never <code>null</code>.</p>



<h2 class="wp-block-heading"><a href="#why-so-many-nulls" aria-hidden="true" class="aal_anchor" id="why-so-many-nulls"><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>Why so many nulls?</h2>



<p>As a Kotlin developer, you may wonder why so many schemas make most of their fields nullable. And why is nullable the default in the schema SDL language anyway?</p>



<p>There can be multiple reasons but an important one has to do with error handling. In GraphQL, when an error happens, a response can be partial: fields that <strong>could</strong> be resolved will be returned. Fields that <strong>couldn’t</strong> will be <code>null</code>, <strong>if the field’s type is nullable</strong>. If not, then the field’s whole parent will be <code>null</code> , if possible, and so on, until we reach the root field, <code>data</code>, which is nullable. This is known as errors <a href="https://spec.graphql.org/draft/#sel-FAPHRPDTAACVAn-e">“bubbling up”</a>.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="331" src="https://wp.apollographql.com/wp-content/uploads/2023/02/Screenshot-2023-02-24-at-20.08.16-1024x331.png" alt="" class="wp-image-19746" srcset="https://wp.apollographql.com/wp-content/uploads/2023/02/Screenshot-2023-02-24-at-20.08.16-1024x331.png 1024w, https://wp.apollographql.com/wp-content/uploads/2023/02/Screenshot-2023-02-24-at-20.08.16-300x97.png 300w, https://wp.apollographql.com/wp-content/uploads/2023/02/Screenshot-2023-02-24-at-20.08.16-768x248.png 768w, https://wp.apollographql.com/wp-content/uploads/2023/02/Screenshot-2023-02-24-at-20.08.16-1536x496.png 1536w, https://wp.apollographql.com/wp-content/uploads/2023/02/Screenshot-2023-02-24-at-20.08.16-2048x662.png 2048w, https://wp.apollographql.com/wp-content/uploads/2023/02/Screenshot-2023-02-24-at-20.08.16-1200x388.png 1200w, https://wp.apollographql.com/wp-content/uploads/2023/02/Screenshot-2023-02-24-at-20.08.16-1980x640.png 1980w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /></figure>



<p>There it is: if you want partial results, <code>null</code> is unavoidable. …However there are times when partial results won’t be sent, or certain field being nullable doesn’t make much sense. In those cases, you can enforce non-nullability on the client.</p>



<h2 class="wp-block-heading"><a href="#enforcing-non-nullability" aria-hidden="true" class="aal_anchor" id="enforcing-non-nullability"><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>Enforcing non-nullability</h2>



<p>Dealing with nullable fields can be tedious:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-kotlin">firstName = data.results?.get(0)?.user?.firstName ?: &quot;&quot;
// or
firstName = data.results!![0]!!.user!!.firstName!!
</code></pre>



<p><code>results</code>, <code>user</code>, and <code>firstName</code> may be nullable according to the schema, but if you happen to know it can’t happen here, it would be nice to tell the machine <em>“Actually, this field will never be null. Trust me, I know what I’m doing!”</em> 😅.</p>



<p>That’s what Apollo Kotlin’s <a href="https://www.apollographql.com/docs/kotlin/advanced/nonnull"><code>@nonnull</code> directive</a> does: with it, you instruct the codegen to <em>act as if</em> the fields were non-nullable:</p>



<p>Query:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-graphql">query FirstName {
  results @nonnull {
    user @nonnull {
      firstName @nonnull
    }
  }
}</code></pre>



<p>🔍 Notice that <code>results</code> is non-nullable but the type parameter <code>Result?</code> still is. At the moment non-nullability can’t be enforced on the <em>elements</em> of a list.</p>



<p>Generated models:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-kotlin">data class Data(
  val results: List&lt;Result?&gt;  // ← non-nullable
)

data class Result(
  val user: User  // ← non-nullable
)

data class User(
  val firstName: String  // ← non-nullable
)</code></pre>



<p>You can also mark fields as <code>@nonnull</code> at the <strong>schema level</strong>, to avoid repeating the directive in all your queries:</p>



<p>extra.graphqls:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-graphql">extend type Query @nonnull(fields: &quot;results&quot;)
extend type Results @nonnull(fields: &quot;user&quot;)
extend type User @nonnull(fields: &quot;firstName&quot;)</code></pre>



<p>💡 If you like this feature, you’re not alone &#8211; that is why a similar feature should soon be part of the official GraphQL spec. <a href="https://github.com/graphql/graphql-wg/blob/main/rfcs/ClientControlledNullability.md">“Client Controlled Nullability”</a>, currently an RFC, will allow you to mark fields in queries as non-nullable, with a new <code>!</code> based syntax. Non-nullable list elements will also be supported!</p>



<h2 class="wp-block-heading"><a href="#input-values-null-vs-absent" aria-hidden="true" class="aal_anchor" id="input-values-null-vs-absent"><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>Input values: null vs absent</h2>



<p>In GraphQL, when an <strong>argument</strong> or an <strong>input object field</strong> is of a nullable type, it actually <a href="https://spec.graphql.org/draft/#sel-GAFdRHABABsC0pB">means 2 things</a>:</p>



<ul class="wp-block-list">
<li>it can be passed as <code>null</code> (present, with a value of <code>null</code>)</li>



<li>it can be omitted altogether (absent)</li>
</ul>



<p>And these two things can have a different meaning for your backend. For instance:</p>



<p>Schema:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-graphql">type Mutation {
  updateUser(id: ID!, user: UpdateUserInput!): Boolean!
}

input UpdateUserInput {
  firstName: String
  nickname: String
}</code></pre>



<p>Mutations:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-graphql">mutation UpdateFirstNameAndResetNickname {
  updateUser(id: 1, user: {firstName: &quot;Robin&quot;, nickname: null})
}

mutation UpdateFirstName {
  updateUser(id: 1, user: {firstName: &quot;Robin&quot;})
}</code></pre>



<p>In the first mutation, we explicitly set nickname to <code>null</code>; in the second one, we don’t pass a value for nickname: the backend won’t touch it.</p>



<p>Apollo Kotlin reflects this in the generated input models by using the <code>Optional</code> class:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-kotlin">data class UpdateUserInput {
  val firstName: Optional&lt;String?&gt; = Optional.Absent,
  val lastName: Optional&lt;String?&gt; = Optional.Absent,
  val nickame: Optional&lt;String?&gt; = Optional.Absent,
}</code></pre>



<p>Nullable fields will be <strong>absent</strong> by default, but you can explicitly set them to <code>null</code> with <code>Optional.present(null)</code>.</p>



<h2 class="wp-block-heading"><a href="#operation-variables" aria-hidden="true" class="aal_anchor" id="operation-variables"><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>Operation variables</h2>



<p>Just like input values, operation variables can be nullable, and when they are, they can be passed as <code>null</code> or be omitted. Here too, they will therefore be generated with <code>Optional</code>.</p>



<p>However this is often not desirable: after all, if you wrote your operation to accept an argument, it is (usually!) because you want to pass a value for it, even if that value is <code>null</code>. And wouldn’t it be nice to be able to write <code>MyQuery(null)</code> rather than <code>MyQuery(Optional.present(null))</code>?</p>



<p>We’ve got you covered! Use Apollo Kotlin’s <code>@optional</code> directive:</p>



<p>Mutation:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-graphql">mutation SetNickname($id: ID!, $nickname: String @optional(if: false)) {
  updateUser(id: $id, user: {nickname: $nickname})
}</code></pre>



<p>Generated code:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-kotlin">data class SetNicknameMutation(
  val id: String,
  val nickname: String?,  // ← no Optional
) {
  // ...
}</code></pre>



<p>This can also be configured <a href="https://www.apollographql.com/docs/kotlin/advanced/operation-variables/#making-nullable-variables-non-optional">once globally</a> if preferred.</p>



<h2 class="wp-block-heading"><a href="#what-about-java" aria-hidden="true" class="aal_anchor" id="what-about-java"><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>What about Java?</h2>



<p>In addition to Kotlin, Apollo Kotlin can also generate Java code.<br>Java doesn’t have a strong support for nullability, but there are tools that can help:</p>



<ul class="wp-block-list">
<li>annotating the fields with <code>@Nullable</code> or <code>@NotNull</code></li>



<li>wrapping nullable types in <code>Optional</code></li>
</ul>



<p>Apollo Kotlin <a href="https://apollographql.github.io/apollo-kotlin/kdoc/apollo-gradle-plugin-external/com.apollographql.apollo3.gradle.api/-service/nullable-field-style.html">can do both</a>, with several flavors to choose from for each.</p>



<p>💡 With input values and operation arguments, you may encounter things like <code>Optional&lt;Optional&lt;String&gt;&gt;</code> . This can be surprising at first, but it makes sense when you think about it: the 1st Optional represents the presence or not of the value, the 2nd one represents nullability. It’s the Java equivalent of <code>Optional&lt;String?&gt;</code> .</p>



<h2 class="wp-block-heading"><a href="#in-a-nullshell" aria-hidden="true" class="aal_anchor" id="in-a-nullshell"><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>In a nullshell</h2>



<p>GraphQL and Kotlin 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 if the details of handling null vs absent can get complicated for input values.</p>



<p>I hope this post cleared some of the confusion around this and gave you more tools to deal with nullability in your codebase and avoid those costly <code>NullPointerException</code>! </p>



<p>As always, feedback is welcome. don’t hesitate to reach out on <a href="https://github.com/apollographql/apollo-kotlin">GitHub</a>, the <a href="https://discord.gg/graphos">Apollo Community</a>, or the <a href="https://slack.kotl.in/">Kotlin Slack</a>!</p>


Nullability in GraphQL and Apollo Kotlin


<p>Happy New Year everyone 🥳. I hope 2023 brings you joy, happiness and loads of type safety!</p>



<p>To kickstart the year, here’s a small list of tips &amp; tricks for working with GraphQL in a Kotlin app. These tips have nothing in common besides the fact that they are easy to implement and will make your life easier.</p>



<p>It’s a list of things that came up in GitHub issues, conferences and/or other discussions. Very often the GraphQL setup was been done some years ago and it’s easy to miss these quality of life improvements. </p>



<p>It might be that you’re doing some or all of them already. If that’s the case then congrats, you’ve earned yourself a good cup of coffee ☕! If not, let’s dive in (and grab a good cup of coffee too 😃!).</p>



<h1 class="wp-block-heading"><a href="#1-use-sdl-for-your-schema" aria-hidden="true" class="aal_anchor" id="1-use-sdl-for-your-schema"><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>1. Use SDL for your schema</h1>



<p>Early versions of Apollo Kotlin only had support for <a href="https://graphql.org/learn/introspection/">introspection</a> JSON. This is convenient because you can get it directly from your GraphQL endpoint. It is <strong>very</strong> verbose though and reading it is <strong>very</strong> cumbersome. To give you and idea, here’s a small sample (full JSON available <a href="https://github.com/apollographql/apollo-kotlin/blob/05f2a3295517fb7a64c2259c38b453a37f3c4d19/libraries/apollo-gradle-plugin/testProjects/multiplatform/src/commonMain/graphql/schema.json#L7">here</a>):</p>



<pre class="wp-block-prismatic-blocks"><code class="language-json">{
  &quot;data&quot;: {
    &quot;__schema&quot;: {
      &quot;queryType&quot;: {
        &quot;name&quot;: &quot;Root&quot;
      },
      &quot;mutationType&quot;: null,
      &quot;subscriptionType&quot;: null,
      &quot;types&quot;: [
        {
          &quot;kind&quot;: &quot;OBJECT&quot;,
          &quot;name&quot;: &quot;Root&quot;,
          &quot;description&quot;: null,
          &quot;fields&quot;: [
            // ~500 lines skipped
          ]
        },
        // ~5000 lines skipped 
      ],
      // ...
    }
  }
}</code></pre>



<p>All in all, the introspection JSON is 5843 lines long for ~50 actual GraphQL types. That’s way too much. Thankfully, <a href="https://www.apollographql.com/tutorials/lift-off-part1/schema-definition-language-sdl">SDL</a> makes it a lot more concise. SDL is <a href="https://graphql.org/learn/schema/">the part of the GraphQL language</a> that deals with type definitions. The same schema translated to SDL looks like this (full SDL available <a href="https://gist.github.com/martinbonnin/e1d9773521e0e4033c829d9f743820c6">here</a>):</p>



<pre class="wp-block-prismatic-blocks"><code class="language-graphql">type Root {
  allFilms(after: String, first: Int, before: String, last: Int): FilmsConnection

  # ~30 lines skipped
}

&quot;&quot;&quot;
A single film.
&quot;&quot;&quot;
type Film implements Node {
  &quot;&quot;&quot;
  The title of this film.
  &quot;&quot;&quot;
  title: String

  # ~50 lines skipped
}

# more types</code></pre>



<p>Much better, right? The good news is you can convert your existing <code>schema.json</code> to a <code>schema.graphqls</code> SDL file:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-">$ ./gradlew convertApolloSchema --from src/main/graphql/schema.json
  --to src/main/graphql/schema.graphqls
$ rm src/main/graphql/schema.json</code></pre>



<p>Moving forward, when updating your schema, you can ask your backend team for the SDL file or directly convert on the fly:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-">$ ./gradlew downloadServiceApolloSchemaFromIntrospection</code></pre>



<p>If your schema has a <code>.graphqls</code> extension, Apollo Kotlin will recognize it and convert it automatically to SDL.</p>



<h1 class="wp-block-heading"><a href="#2-update-your-schema-in-github-actions" aria-hidden="true" class="aal_anchor" id="2-update-your-schema-in-github-actions"><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>2. Update your schema in GitHub actions</h1>



<p>Talking about updating your schema, typing <code>./gradlew downloadServiceApolloSchemaFromIntrospection</code> is verbose and it&#8217;s easy to forget doing it. You could tweak your build to download it every time but this has two major drawbacks:</p>



<ol class="wp-block-list">
<li>it makes your builds longer as they now need to download a file all the time.</li>



<li>it makes your builds non-reproducible as the schema will depend on when you run your builds. If you checkout an older tag, it will download your recent schema.</li>
</ol>



<p>For these reasons, we recommend committing your schema in source control and updating it in a cron job.<br>We have created a GitHub action for this: <a href="https://github.com/apollographql/update-graphql-schema">update-graphql-schema</a>. To use it, create a new GitHub workflow file named <code>update-graphql-schema.yaml</code> and copy paste the following contents (update endpoint and schema):</p>



<pre class="wp-block-prismatic-blocks"><code class="language-yaml">name: Update GraphQL schema
on:
  schedule:
    # every night at midnight (GitHub actions time)
    - cron: &quot;0 0 * * *&quot;

jobs:
  update:
    runs-on: ubuntu-20.04
    steps:
      - uses: actions/checkout@v2
      - uses: apollographql/update-graphql-schema@4b4517cad731e2564488f203de81937dcc4ef92e #main
        with:
          schema: &quot;src/main/graphql/schema.graphqls&quot;

          # With GraphOS
          key: &quot;service:fullstack-tutorial:abc123&quot;

          # With introspection
          endpoint: &quot;https://example.com/graphql&quot;
</code></pre>



<p>Whenever your schema changes, a new pull request is created:</p>



<figure class="wp-block-image size-full"><img loading="lazy" decoding="async" width="906" height="538" src="https://wp.apollographql.com/wp-content/uploads/2023/01/Screenshot-2023-01-04-at-15.50.43.png" alt="" class="wp-image-19081" srcset="https://wp.apollographql.com/wp-content/uploads/2023/01/Screenshot-2023-01-04-at-15.50.43.png 906w, https://wp.apollographql.com/wp-content/uploads/2023/01/Screenshot-2023-01-04-at-15.50.43-300x178.png 300w, https://wp.apollographql.com/wp-content/uploads/2023/01/Screenshot-2023-01-04-at-15.50.43-768x456.png 768w" sizes="auto, (max-width: 906px) 100vw, 906px" /></figure>



<p>You can view in action in the Confetti repo (<a href="https://github.com/joreilly/Confetti/blob/201cc4cb23bd1cd61ba116a3e4bbb82919eb52ea/.github/workflows/update-schema.yml">yaml file</a>, <a href="https://github.com/joreilly/Confetti/pull/130">example pull request</a>).<br>Not only does it save you from updating manually but if using SDL, it shows the changes in a nice visual way!</p>



<h1 class="wp-block-heading"><a href="#3-fail-on-deprecated-fields-usages" aria-hidden="true" class="aal_anchor" id="3-fail-on-deprecated-fields-usages"><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>3. Fail on deprecated fields usages</h1>



<p>When you update your schema, your new schema might contain newly <a href="https://www.apollographql.com/tutorials/lift-off-part5/field-deprecation">deprecated fields</a>. That’s one of the nice things with GraphQL. You can evolve your API progressively. When a field is deprecated, it’s good to stop using it so that the backend team can ultimately remove it.</p>



<p>By default Apollo Kotlin does two things:</p>



<ol class="wp-block-list">
<li>It displays a warning during codegen.</li>



<li>It marks generated classes with <a href="https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-deprecated/">Kotlin’s <code>@Deprecated</code> annotation.</a> This way, your IDE can show it as strikethrough and <code>kotlinc</code> can itself display a warning.</li>
</ol>



<p>Warnings are easy to ignore though and if you do not edit the code that is using deprecated fields, you might continue using the field for longer than necessary.</p>



<p>If you want to be strict about not using deprecated GraphQL fields, set <code>failOnWarnings</code> to true:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-kotlin">apollo {
    service(&quot;service&quot;) {
       packageName.set(&quot;com.example&quot;)

       warnOnDeprecatedUsages.set(true)
       failOnWarnings.set(true)
    }
}</code></pre>



<p>Whenever you’ll try to use a deprecated field your build will fail (and that’s a good thing!):</p>



<pre class="wp-block-prismatic-blocks"><code class="language-">&gt; Task :shared:generateServiceApolloSources FAILED
w: /Users/mbonnin/git/Confetti/shared/src/commonMain/graphql/Queries.graphql: (17, 9): Apollo: Use of deprecated field `name`

FAILURE: Build failed with an exception.

* What went wrong:
Execution failed for task &#039;:shared:generateServiceApolloSources&#039;.
&gt; Apollo: Warnings found and &#039;failOnWarnings&#039; is true, aborting.</code></pre>



<h1 class="wp-block-heading"><a href="#4-try-out-the-data-builders" aria-hidden="true" class="aal_anchor" id="4-try-out-the-data-builders"><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>4. Try out the data builders</h1>



<p>When it comes to testing, you had 2 options with early versions of Apollo Kotlin:</p>



<ol class="wp-block-list">
<li>enqueue a fake JSON into a mock server like <a href="https://github.com/square/okhttp/tree/master/mockwebserver">OkHttp MockWebServer</a>. This works but requires maintaining a set of <code>.json</code> Strings that are not easy to create manually. You could intercept the network traffic to get some real life samples but doing that and maintaining it is cumbersome</li>



<li>call the model constructors manually. This works too but for models that have a lot of properties, it’s tedious to pass them all. What’s more merge fields require to duplicate some properties and it’s easy to create inconsistent models by passing a wrong <code>__typename</code></li>
</ol>



<p>Apollo Kotlin 3.6.0 introduced <a href="https://www.apollographql.com/docs/kotlin/testing/data-builders">data builders</a>. Data builders intend to solve both issues by generating builders for your schema types.</p>



<p></p>



<p><em>Note:</em> contrary to the models, the data builders are based on the schema and not the operation. This means it is possible to set a value in your builders that is never going to be read by a certain operation. This is a tradeoff to avoid the exponential blowup issues that come with <a href="https://github.com/apollographql/apollo-kotlin/issues/3144">responseBased codegen</a> and allows sharing builders amongst different operations.</p>



<p>To enable the data builders, set <code>generateDataBuilders</code> to true in your Gradle files:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-kotlin">apollo {
  service(&quot;service&quot;) {
    // ...
    generateDataBuilders.set(true)
  }
}</code></pre>



<p>That generates builders that you can then use with a <code>Data {}</code> function:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-kotlin">  val data = GetHeroQuery.Data {
    hero = buildHuman {
      firstName = &quot;John&quot;
      age = 42
      friends = listOf(
        buildHuman {
          firstName = &quot;Jane&quot;
        }, 
        buildHuman {
          lastName = &quot;Doe&quot;
        }
      )
      ship = buildStarship {
        model = &quot;X-Wing&quot;
      }
    }
  }</code></pre>



<p>To get a Json out of it, you can use <code>Data.toJsonString()</code> (JVM/Android only):</p>



<pre class="wp-block-prismatic-blocks"><code class="language-kotlin">val data = GetHeroQuery.Data { ... }
mockServer.enqueue(data.toJsonString())</code></pre>



<p>You can read more in the <a href="https://www.apollographql.com/docs/kotlin/testing/data-builders">official doc</a></p>



<h1 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>Conclusion</h1>



<p>That’s it for now! I hope you enjoyed this little tour. As always, <a href="https://github.com/apollographql/apollo-kotlin/issues/new/choose">feedback is very welcome</a>! You can also take a look at the <a href="https://github.com/apollographql/apollo-kotlin/blob/main/ROADMAP.md">ROADMAP</a> to get a glimpse of what’s coming in 2023.</p>


4 New Year’s resolutions for your Kotlin apps


<p>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>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>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>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><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><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>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>The most basic way to think about this is the following equation:</p>



<p><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>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>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>For example, given the following schema:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-graphql">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>And the following query:</p>



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



<p>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">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>Because the <code>HeroAndFriendsNames</code> query doesn&#8217;t fetch <code>appearsIn</code>, this property is not part of the returned result type and cannot be accessed here. Similarly, <code>id</code> is only accessible in <code>Friend</code>, not in <code>Hero</code>.</p>



<p>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>A named fragment is defined in a <code>.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>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">fragment HeroDetails on Character {
  name
  appearsIn
}</code></pre>



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



<p>Apollo iOS generates a type-safe model for the <code>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">struct HeroDetails: MySchema.SelectionSet, Fragment {
  let name: String
  let appearsIn: [Episode]
}</code></pre>



<p>The result data models generated for the <code>HeroAndFriendsQuery</code> will include the fields from the <code>HeroDetails</code> fragment and are able to be converted into the <code>HeroDetails</code> fragment model.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-swift">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>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><strong>The Codegen CLI has three primary commands:</strong></p>



<ul class="wp-block-list">
<li><strong>Initialize</strong>: Initializes an <code>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>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>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>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>


Apollo iOS Client 1.0 with improved code generation


<p><a rel="noreferrer noopener" href="https://www.apollographql.com/blog/mobile/kotlin/whats-new-with-multiplatform-in-apollo-kotlin/" target="_blank">Back in May</a>, we shared about how Apollo Kotlin started supporting the Hierarchical project structure. Following the Kotlin Multiplatform ecosystem, here is some more news, this time about the new Memory Manager.</p>



<h2 class="wp-block-heading"><a href="#kotlin-natives-memory-manager" aria-hidden="true" class="aal_anchor" id="kotlin-natives-memory-manager"><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>Kotlin Native’s Memory Manager</h2>



<p>Since its early days, Kotlin Native has had <a href="https://kotlinlang.org/docs/multiplatform-mobile-concurrency-overview.html" target="_blank" rel="noreferrer noopener">specific rules</a> regarding multithreading and immutability:</p>



<ul class="wp-block-list"><li>objects could only be accessed from the thread they were created in</li><li>unless they had been “frozen”, in which case they could be accessed by multiple threads, but became immutable</li></ul>



<p>These native-specific restrictions have been a source of friction in writing and sharing code among targets.</p>



<p>In Apollo Kotlin, following these rules meant that the library had to be accessed strictly from the Main thread on Apple targets, which was a hindrance.</p>



<p>Kotlin Native’s <a href="https://blog.jetbrains.com/kotlin/2021/08/try-the-new-kotlin-native-memory-manager-development-preview/" target="_blank" rel="noreferrer noopener">new memory manager</a> (<a href="https://kotlinlang.org/docs/whatsnew-eap.html#the-new-kotlin-native-memory-manager-is-enabled-by-default" target="_blank" rel="noreferrer noopener">now beta</a>) removes these specificities and with it, native code can for the most part be written like JVM code when it comes to concurrency. After some months of being opt-in, it will be the default starting with <a href="https://blog.jetbrains.com/kotlin/2022/08/kotlin-1-7-20-beta/" target="_blank" rel="noreferrer noopener">Kotlin 1.7.20</a>.</p>



<p><strong>Apollo Kotlin made the switch in <a href="https://github.com/apollographql/apollo-kotlin/releases/tag/v3.5.0" target="_blank" rel="noreferrer noopener">version 3.5.0</a>.</strong></p>



<p>What does it mean for you?</p>



<ul class="wp-block-list"><li>If your Multiplatform / Native project hasn’t yet switched to the new MM, you will need to <a href="https://github.com/JetBrains/kotlin/blob/master/kotlin-native/NEW_MM.md#enable-the-new-mm" target="_blank" rel="noreferrer noopener">do so</a> before upgrading to 3.5.0:</li></ul>



<pre class="wp-block-prismatic-blocks"><code class="language-kotlin">// build.gradle.kts

kotlin.targets.withType(KotlinNativeTarget::class.java) {
    binaries.all {
        binaryOptions[&quot;memoryModel&quot;] = &quot;experimental&quot;
    }
}</code></pre>



<ul class="wp-block-list"><li>Calling the library exclusively from the Main thread on Apple is no longer required *</li><li>You can now use <a rel="noreferrer noopener" href="https://github.com/Kotlin/kotlinx.coroutines/blob/master/kotlinx-coroutines-test/README.md" target="_blank">Kotlin’s <code>runTest</code></a> in all unit tests</li><li>Initial benchmarks <a rel="noreferrer noopener" href="https://github.com/apollographql/apollo-kotlin/pull/4287/files?w=1#diff-aead75359419ef1647be74310bd7093e4cc2d9393917d17029d5fcc5e11ce1ef" target="_blank">indicate</a> that performance is improved by up to 45% under the new memory manager!</li></ul>



<blockquote class="wp-block-quote is-layout-flow wp-block-quote-is-layout-flow"><p><em>*Suspend functions still need to be run from the Main thread from Swift / Objective C code &#8211; see <a rel="noreferrer noopener" href="https://youtrack.jetbrains.com/issue/KT-51297" target="_blank">KT-51297</a> for more information.</em></p></blockquote>



<h2 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>Conclusion</h2>



<p>Kotlin Multiplatform continues to evolve, and with its new Memory Manager, it is becoming easier to use. By adopting it in its codebase, Apollo Kotlin 3.5.0 is able to get rid of a few threading and testing-related intricacies. We will continue to closely follow Kotlin Multiplatform’s evolutions so you can take advantage of it in your projects! As always, we love to hear your feedback, on <a href="https://github.com/apollographql/apollo-kotlin" target="_blank" rel="noreferrer noopener">GitHub</a>, the <a href="https://community.apollographql.com/" target="_blank" rel="noreferrer noopener">Apollo Community</a>, or the <a href="https://slack.kotl.in/" target="_blank" rel="noreferrer noopener">Kotlin Slack</a>.</p>


Apollo Kotlin: New Multiplatform Memory Manager


<p><em>« Write once, run anywhere »</em>: that age-old dream is still alive today. That is why, when making Apollo Kotlin (then known as Apollo Android) a 100% Kotlin codebase, making it also <a href="https://kotlinlang.org/docs/multiplatform.html">Multiplatform</a> was inevitable. The potential advantages for users would well be worth the overhead of writing agnostic code. Since then, the Multiplatform ecosystem has been evolving and Apollo Kotlin is keeping up with it.</p>



<h2 class="wp-block-heading"><a href="#hierarchical-project-structure" aria-hidden="true" class="aal_anchor" id="hierarchical-project-structure"><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>Hierarchical project structure</h2>



<p>Let’s start with the <a href="https://kotlinlang.org/docs/multiplatform-hierarchy.html">hierarchical project structure</a> (a.k.a. HMPP) which enables code-sharing among several platforms &#8211; for instance, having a unique source set for both iOS Arm64 and X64 is now achieved without any custom scripting. This was introduced <a href="https://kotlinlang.org/docs/whatsnew14.html#sharing-code-in-several-targets-with-the-hierarchical-project-structure">with Kotlin 1.4.0</a> and is now enabled by default <a href="https://kotlinlang.org/docs/whatsnew1620.html#kotlin-multiplatform">since Kotlin 1.6.20</a>.</p>



<p>Apollo Kotlin has made the switch in the <a href="https://github.com/apollographql/apollo-kotlin/releases/tag/v3.3.0">latest release, 3.3.0</a>.</p>



<p>What this means for your project:</p>



<ul class="wp-block-list"><li>If you’re already using Kotlin 1.6.20+, you’re good to go ✅! If not, we recommend you update to it.</li><li>Otherwise, enable HMPP on your project:</li></ul>



<pre class="wp-block-prismatic-blocks"><code class="language-ini">kotlin.mpp.enableGranularSourceSetsMetadata=true
kotlin.native.enableDependencyPropagation=false</code></pre>



<p>When using Kotlin &lt; 1.6.20, you’ll also need to disable the <code>KotlinMetadata</code> task due to <a href="https://youtrack.jetbrains.com/issue/KT-51970">issue KT-51970</a>, like so:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-kotlin">  // Workaround for https://youtrack.jetbrains.com/issue/KT-51970
  afterEvaluate {
    afterEvaluate {
      tasks.configureEach {
        if (
            name.startsWith(&quot;compile&quot;)
            &amp;&amp; name.endsWith(&quot;KotlinMetadata&quot;)
        ) {
          println(&quot;disabling ${this@subprojects}:$name&quot;)
          enabled = false
        }
      }
    }
  }</code></pre>



<p>This workaround is not applicable if your project is a library, though &#8211; in that case you’ll need to update to Kotlin 1.6.20+.</p>



<h2 class="wp-block-heading"><a href="#new-memory-manager-in-kotlin-native-projects" aria-hidden="true" class="aal_anchor" id="new-memory-manager-in-kotlin-native-projects"><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>New Memory Manager in Kotlin Native Projects</h2>



<p>If you have been writing native code in Kotlin, you probably have encountered these messages:</p>



<ul class="wp-block-list"><li><code>IncorrectDereferenceException: illegal attempt to access non-shared com.example.MyObj from other thread</code></li><li><code>InvalidMutabilityException: mutation attempt of frozen com.example.MyObj</code></li></ul>



<p>These are due to Kotlin Native’s <a href="https://kotlinlang.org/docs/multiplatform-mobile-concurrency-overview.html">specific concurrency rules</a>.</p>



<p>The <a href="https://github.com/JetBrains/kotlin/blob/master/kotlin-native/NEW_MM.md">new memory manager</a> (currently alpha) makes these messages a thing of the past and multiplatform development a definitely nicer experience!<br>Apollo Kotlin is already compatible, so you can enable it on your project with this flag:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-ini">kotlin.native.binary.memoryModel=experimental</code></pre>



<p>Since the memory manager concerns executables rather than libraries, Apollo Kotlin’s code must abide by the old rules to stay compatible with projects using the old manager &#8211; which we’ll keep on doing in the short term.</p>



<figure class="wp-block-table"><table><thead><tr><th class="has-text-align-center" data-align="center">Apollo Kotlin</th><th class="has-text-align-center" data-align="center">Your project</th><th class="has-text-align-center" data-align="center">Compatibility</th></tr></thead><tbody><tr><td class="has-text-align-center" data-align="center">Assumes old MM (today)</td><td class="has-text-align-center" data-align="center">Old MM</td><td class="has-text-align-center" data-align="center">✅</td></tr><tr><td class="has-text-align-center" data-align="center">Assumes old MM (today)</td><td class="has-text-align-center" data-align="center">New MM</td><td class="has-text-align-center" data-align="center">✅</td></tr><tr><td class="has-text-align-center" data-align="center">Assumes new MM (the future)</td><td class="has-text-align-center" data-align="center">New MM</td><td class="has-text-align-center" data-align="center">✅</td></tr><tr><td class="has-text-align-center" data-align="center">Assumes new MM (the future)</td><td class="has-text-align-center" data-align="center">Old MM</td><td class="has-text-align-center" data-align="center">💥</td></tr></tbody></table></figure>



<p>What’s next? We will monitor feedback and the progress on the new manager and eventually adopt it in Apollo Kotlin’s code.</p>



<p>To help us decide on the right time to do this, we’d love your comments on <a href="https://github.com/apollographql/apollo-kotlin/issues/4100">ticket #4100</a>, or hop on the <code>#apollo-kotlin</code> channel on the <a href="https://slack.kotl.in/">Kotlin Slack</a>!</p>



<h2 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>Conclusion</h2>



<p>Today, Kotlin Multiplatform is still considered experimental, but it is becoming solid and nice to use. Apollo Kotlin 3.3.0 has adopted the HMPP convention and we will continue to closely follow Kotlin Multiplatform’s evolutions so you can take advantage of it in your projects! As always, we love to hear your feedback, on <a href="https://github.com/apollographql/apollo-kotlin">GitHub</a>, the <a href="https://community.apollographql.com/">Apollo Community</a>, or the <a href="https://slack.kotl.in/">Kotlin Slack</a>.</p>


What's new with Multiplatform in Apollo Kotlin

Mobile

New GraphQL courses for iOS and Android development

More expressive schemas with @oneOf

Journey to K2: using the New Compiler in Apollo Kotlin

How Apollo Manages Swift Packages in a Monorepo with Git Subtrees

GraphQLNullable is not a trap!

How Apollo Kotlin leverages Gradle Enterprise to Rev Up Build Times

Announcing the Apollo Kotlin plugin for Android Studio and IntelliJ IDEA

Past posts

Community Update: Apollo Client, Apollo iOS, and Apollo Kotlin

Nullability in GraphQL and Apollo Kotlin

4 New Year’s resolutions for your Kotlin apps

Apollo iOS Client 1.0 with improved code generation

Apollo Kotlin: New Multiplatform Memory Manager

What’s new with Multiplatform in Apollo Kotlin

Mobile

New GraphQL courses for iOS and Android development

More expressive schemas with @oneOf

Journey to K2: using the New Compiler in Apollo Kotlin

How Apollo Manages Swift Packages in a Monorepo with Git Subtrees

GraphQLNullable is not a trap!

How Apollo Kotlin leverages Gradle Enterprise to Rev Up Build Times

Announcing the Apollo Kotlin plugin for Android Studio and IntelliJ IDEA

Past posts

Community Update: Apollo Client, Apollo iOS, and Apollo Kotlin

Nullability in GraphQL and Apollo Kotlin

4 New Year’s resolutions for your Kotlin apps

Apollo iOS Client 1.0 with improved code generation

Apollo Kotlin: New Multiplatform Memory Manager

What’s new with Multiplatform in Apollo Kotlin

Stay in our orbit