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 4 is the new major version of Apollo Kotlin. It builds on top of Apollo Kotlin 3 and brings a number of tooling and API improvements:</p>



<ul class="wp-block-list">
<li>A brand new IDE plugin for all your refactoring needs.</li>



<li>Improvement to the error handling APIs, making it easier to handle errors in a single place.</li>



<li>WasmJs support.</li>



<li>A multiplatform GraphQL parser.</li>



<li>A preview of semantic nullability.</li>



<li>Network monitoring API, new WebSocket APIs and more …</li>
</ul>



<p>For a comprehensive list of all changes, please review the <a href="https://github.com/apollographql/apollo-kotlin/releases/tag/v4.0.0">full changelog</a>.</p>



<p>If you&#8217;re currently using Apollo Kotlin 3, refer to the <a href="https://www.apollographql.com/docs/kotlin/v4/migration/4.0/#moved-artifacts">migration guide</a> for step-by-step migration instructions.</p>



<p>Or read on for a brief summary of the key updates and a preview of what&#8217;s on the horizon.</p>



<h2 class="wp-block-heading"><a href="#android-studio-intellij-plugin" aria-hidden="true" class="aal_anchor" id="android-studio-intellij-plugin"><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>Android Studio/IntelliJ plugin</h2>



<p>If you’re using Android Studio or IntelliJ, <a href="https://www.apollographql.com/docs/kotlin/v4/testing/android-studio-plugin/">you can now download the Apollo IntelliJ plugin in the IntelliJ marketplace</a> and get even more help from your IDE.</p>



<p>Apollo IDE plugin core features include:</p>



<ul class="wp-block-list">
<li>On the fly code generation</li>



<li>GraphQL &lt;-> Kotlin navigation</li>



<li>Unused field inspection</li>



<li>High Field latency inspection</li>



<li>Normalized cache viewer</li>



<li>Schema download </li>



<li>Automatic migration</li>
</ul>



<p>That last point means you can now use the plugin to automate most of your v3 -&gt; v4 migration.</p>



<p><img loading="lazy" decoding="async" src="https://lh7-us.googleusercontent.com/docsz/AD_4nXdaWp_FZSNQWfiwe6FNOOsEcoK1pc4K1wAsu7BX6Am-8yP7Rdjs0ZPGbgppgMND00Yvs4iBQbOlY9IBVwwYhjUNrHUq8_vIeAGxaxKNvL7S_aG00mq18dCdD8PYBtBbQO5-_8XWu5e1wL2MtRvZykK-86SW?key=12X6ltZW9oZBbxKegGgpWw" width="668" height="463"></p>



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



<p>With the release of Apollo Kotlin 4, we&#8217;ve achieved a significant milestone where our core APIs—including code generation, parsers, and interceptors—are now stable. This stability means we don’t anticipate any major overhauls like the transition from version 2 to 3, though the landscape of Kotlin and GraphQL continues to evolve rapidly. Developments such as <a href="https://youtrack.jetbrains.com/issue/KT-68296">union types for errors</a> or <a href="https://github.com/graphql/nullability-wg/discussions/58">semantic nullability schemas</a> may necessitate breaking changes in the future.</p>



<p>Looking ahead, our goal is to roll out smaller, more frequent updates, including major versions. This approach will keep the core APIs consistent, enabling us to introduce new features and adapt more swiftly to changes in the environment. To facilitate this, we’ve updated the package name from <code>com.apollographql.apollo3</code> to <code>com.apollographql.apollo</code>.<br><br>With Apollo Kotlin 4, we are also introducing an evolution policy. This policy will steer the development of future versions and ensure that we provide clear deprecation notices, helping you to transition smoothly and confidently.</p>



<h2 class="wp-block-heading"><a href="#multiplatform-graphql-parser" aria-hidden="true" class="aal_anchor" id="multiplatform-graphql-parser"><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>Multiplatform GraphQL parser</h2>



<p>Previously, Apollo Kotlin relied on<a href="https://github.com/graphql/graphql-js" data-type="link" data-id="https://github.com/graphql/graphql-js"> <code>graphql-js</code></a> for parsing GraphQL documents. In version 2, we transitioned to using <a href="https://www.antlr.org/">Antlr</a> to generate parsers from <code>.g4</code> grammars.</p>



<p>With Apollo Kotlin 4, we’ve taken a significant leap forward by developing our <a href="https://github.com/apollographql/apollo-kotlin/pull/5047">own recursive descent</a> parser.</p>



<p>The new parser not only performs up to <a href="https://github.com/apollographql/apollo-kotlin/pull/5047#issue-1780385717">twice </a>as fast as the previous Antlr-based parser in certain scenarios, but it’s also entirely written in Kotlin, ensuring full multiplatform support. This means you can seamlessly integrate it into your Kotlin multiplatform projects just like any other KMP dependency.</p>



<p>Here’s how you can add the new parser to your project:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-kotlin">kotlin {
  sourceSets {
    getByName(&quot;commonMain&quot;) {
      dependencies {
        implementation(&quot;com.apollographql.apollo:apollo-ast&quot;)
      }
    }
  }
}</code></pre>



<p>And here’s how to utilize it at runtime:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-kotlin">  // Parse a document
  val document = &quot;query { hello }&quot;.toGQLDocument()

  // transform/inspect it
  // And serialize it again
  println(document.toUtf8())</code></pre>



<h2 class="wp-block-heading"><a href="#introducing-wasmjs-support" aria-hidden="true" class="aal_anchor" id="introducing-wasmjs-support"><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>Introducing WasmJs support</h2>



<p>Apollo Kotlin 4 now includes support for the WasmJs target, expanding your capabilities to use the generated models and <code>apollo-runtime</code> in a Wasm application. Experience this new feature firsthand by trying out the Confetti wasm demo at <a href="https://wasm.confetti-app.dev/">https://wasm.confetti-app.dev/</a> (<a href="https://github.com/joreilly/Confetti">GitHub</a>).</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="874" height="1024" src="https://wp.apollographql.com/wp-content/uploads/2024/07/Screenshot-2024-07-31-at-17.27.47-874x1024.png" alt="" class="wp-image-23864" srcset="https://wp.apollographql.com/wp-content/uploads/2024/07/Screenshot-2024-07-31-at-17.27.47-874x1024.png 874w, https://wp.apollographql.com/wp-content/uploads/2024/07/Screenshot-2024-07-31-at-17.27.47-256x300.png 256w, https://wp.apollographql.com/wp-content/uploads/2024/07/Screenshot-2024-07-31-at-17.27.47-768x900.png 768w, https://wp.apollographql.com/wp-content/uploads/2024/07/Screenshot-2024-07-31-at-17.27.47-1311x1536.png 1311w, https://wp.apollographql.com/wp-content/uploads/2024/07/Screenshot-2024-07-31-at-17.27.47-1748x2048.png 1748w, https://wp.apollographql.com/wp-content/uploads/2024/07/Screenshot-2024-07-31-at-17.27.47-1200x1406.png 1200w, https://wp.apollographql.com/wp-content/uploads/2024/07/Screenshot-2024-07-31-at-17.27.47.png 1886w" sizes="auto, (max-width: 874px) 100vw, 874px" /></figure>



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



<p>In GraphQL, <a href="https://graphql.org/learn/best-practices/#nullability">fields are traditionally nullable by default</a>. However, the standards set in 2015 don’t always align with the needs of 2024, especially as <a href="https://github.com/graphql/nullability-wg/">the GraphQL community seeks to enhance </a>type safety for languages like TypeScript, Swift, and Kotlin.</p>



<p>Apollo Kotlin 4 introduces two experimental directives, <code>@semanticNonNull</code> and <code>@catch</code>, designed to simplify interactions with nullable fields.</p>



<p>The <code>@semanticNonNull</code> directive is a server-side directive, indicating that a field is guaranteed to be non-null unless an error happens. This directive can be incorporated into your <code>.graphqls</code> schema extensions, enhancing the clarity and reliability of your data models:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-kotlin"># name is never null unless an error happens
extend type User @semanticNonNullField(name: &quot;name&quot;)</code></pre>



<p>On the code generation front, Apollo Kotlin recognizes <code>@semanticNonNullField</code> and accordingly generates non-null Kotlin properties, ensuring that your application code remains type-safe and concise.</p>



<p>Additionally, the <code>@catch</code> directive is a client-side directive for opting into specific error handling strategies during operations. By using <code>@catch</code> in your <code>.graphql</code> operations, you can manage how errors are handled directly within the data context—whether by mapping errors to <code>null</code>, re-throwing them, or using another method:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-kotlin">query GetUser {
  user {
    # map name to FieldResult&lt;String?&gt; instead of stopping parsing
    name @catch(to: RESULT)
  }
}</code></pre>



<p>For a deeper understanding of these enhancements and their implications on your projects, please refer to our detailed <a href="https://www.apollographql.com/docs/kotlin/v4/advanced/nullability#handle-errors-and-receive-partial-data-with-catch">nullability documentation page</a>.</p>



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



<p>Beyond the updates already discussed, Apollo Kotlin 4 introduces several exciting features including support for<a href="https://github.com/graphql/graphql-spec/pull/825"> <code>@oneOf</code></a>, new WebSockets APIs, new low-level Apollo compiler plugin APIs, and new Gradle APIs. For a detailed list of all the enhancements, make sure to read the full changelog.</p>



<p>One significant area poised for further development is the normalized cache, which continues to present challenges. While Apollo Kotlin 3 introduced <a href="https://www.apollographql.com/docs/kotlin/caching/declarative-ids/">&nbsp;<code>@typePolicy</code> and <code>@fieldPolicy</code> for declarative ids</a>, certain scenarios still demand the use of complex programmatic APIs.</p>



<p>Additionally, issues such as garbage collection and invalidation remain unresolved. We aim to address these in version 5.</p>



<p>With the modularization of Apollo Kotlin development has shifted to <a href="https://github.com/apollographql/apollo-kotlin-normalized-cache-incubating/">a separate repository</a>, enabling more agile iteration and improvement.<br>For the latest updates and future plans, please refer to <a href="https://github.com/apollographql/apollo-kotlin/blob/main/ROADMAP.md">the ROADMAP</a> document on what is being worked on.</p>



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



<p>Have a question or wish to discuss GraphQL, Kotlin, or the<a href="https://github.com/apollographql/apollo-kotlin/blob/main/ROADMAP.md"> ROADMAP</a>? We encourage you to connect with us and join the conversation:</p>



<ul class="wp-block-list">
<li><a href="https://github.com/apollographql/apollo-android/issues">Github</a></li>



<li><a href="http://community.apollographql.com/new-topic?category=Help&amp;tags=mobile,client">Community forums</a></li>



<li>Join the <a href="https://app.slack.com/client/T09229ZC6/C01A6KM1SBZ">Apollo KotlinLang slack channel</a> (click <a href="https://slack.kotl.in/">here</a> for an invite).</li>
</ul>



<p>We&#8217;re here to support you and look forward to your insights and contributions!</p>


Apollo Kotlin 4 is now available


<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

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

Office Hours: 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><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

Apollo Kotlin 4 is now available

Journey to K2: using the New Compiler in Apollo Kotlin

How Apollo Kotlin leverages Gradle Enterprise to Rev Up Build Times

Announcing the Apollo Kotlin plugin for Android Studio and IntelliJ IDEA

Office Hours: Apollo Kotlin

Past posts

Nullability in GraphQL and Apollo Kotlin

4 New Year’s resolutions for your Kotlin apps

Apollo Kotlin: New Multiplatform Memory Manager

What’s new with Multiplatform in Apollo Kotlin

The story behind Apollo Kotlin 3 codegen

Mobile

New GraphQL courses for iOS and Android development

More expressive schemas with @oneOf

Apollo Kotlin 4 is now available

Journey to K2: using the New Compiler in Apollo Kotlin

How Apollo Kotlin leverages Gradle Enterprise to Rev Up Build Times

Announcing the Apollo Kotlin plugin for Android Studio and IntelliJ IDEA

Office Hours: Apollo Kotlin

Past posts

Nullability in GraphQL and Apollo Kotlin

4 New Year’s resolutions for your Kotlin apps

Apollo Kotlin: New Multiplatform Memory Manager

What’s new with Multiplatform in Apollo Kotlin

The story behind Apollo Kotlin 3 codegen

Stay in our orbit