<olclass="chapter"><liclass="affix"><ahref="../index.html">Introduction</a></li><liclass="affix"><ahref="../quickstart.html">Quickstart</a></li><liclass="affix"><ahref="../types/index.html">Type System</a></li><li><ahref="../types/objects/defining_objects.html"><strongaria-hidden="true">1.</strong> Defining objects</a></li><li><olclass="section"><li><ahref="../types/objects/complex_fields.html"><strongaria-hidden="true">1.1.</strong> Complex fields</a></li><li><ahref="../types/objects/using_contexts.html"><strongaria-hidden="true">1.2.</strong> Using contexts</a></li><li><ahref="../types/objects/error_handling.html"><strongaria-hidden="true">1.3.</strong> Error handling</a></li></ol></li><li><ahref="../types/other-index.html"><strongaria-hidden="true">2.</strong> Other types</a></li><li><olclass="section"><li><ahref="../types/enums.html"><strongaria-hidden="true">2.1.</strong> Enums</a></li><li><ahref="../types/interfaces.html"class="active"><strongaria-hidden="true">2.2.</strong> Interfaces</a></li><li><ahref="../types/input_objects.html"><strongaria-hidden="true">2.3.</strong> Input objects</a></li><li><ahref="../types/scalars.html"><strongaria-hidden="true">2.4.</strong> Scalars</a></li><li><ahref="../types/unions.html"><strongaria-hidden="true">2.5.</strong> Unions</a></li></ol></li><li><ahref="../schema/schemas_and_mutations.html"><strongaria-hidden="true">3.</strong> Schemas and mutations</a></li><li><ahref="../servers/index.html"><strongaria-hidden="true">4.</strong> Adding A Server</a></li><li><olclass="section"><li><ahref="../servers/official.html"><strongaria-hidden="true">4.1.</strong> Official Server Integrations</a></li><li><olclass="section"><li><ahref="../servers/warp.html"><strongaria-hidden="true">4.1.1.</strong> Warp</a></li><li><ahref="../servers/rocket.html"><strongaria-hidden="true">4.1.2.</strong> Rocket</a></li><li><ahref="../servers/iron.html"><strongaria-hidden="true">4.1.3.</strong> Iron</a></li><li><ahref="../servers/hyper.html"><strongaria-hidden="true">4.1.4.</strong> Hyper</a></li></ol></li><li><ahref="../servers/third-party.html"><strongaria-hidden="true">4.2.</strong> Third Party Integrations</a></li></ol></li><li><ahref="../advanced/index.html"><strongaria-hidden="true">5.</strong> Advanced Topics</a></li><li><olclass="section"><li><ahref="../advanced/introspection.html"><strongaria-hidden="true">5.1.</strong> Introspection</a></li><li><ahref="../advanced/non_struct_objects.html"><strongaria-hidden="true">5.2.</strong> Non-struct objects</a></li><li><ahref="../advanced/implicit_and_explicit_null.html"><strongaria-hidden="true">5.3.</strong> Implicit and explicit null</a></li><li><ahref="../advanced/objects_and_generics.html"><strongaria-hidden="true">5.4.</strong> Objects and generics</a></li><li><ahref="../advanced/multiple_ops_per_request.html"><strongaria-hidden="true">5.5.</strong> Multiple operations per request</a></li><li><ahref="../advanced/dataloaders.html"><strongaria-hidden="true">5.6.</strong> Dataloaders</a></li><li><ahref="../advanced/subscriptions.html"><strongaria-hidden="true">5.7.</strong> Subscriptions</a></li></ol></li></ol>
<buttonid="sidebar-toggle"class="icon-button"type="button"title="Toggle Table of Contents"aria-label="Toggle Table of Contents"aria-controls="sidebar">
<inputtype="search"name="search"id="searchbar"name="searchbar"placeholder="Search this book ..."aria-controls="searchresults-outer"aria-describedby="searchresults-header">
<p><ahref="https://spec.graphql.org/June2018/#sec-Interfaces">GraphQL interfaces</a> map well to interfaces known from common object-oriented languages such as Java or C#, but Rust, unfortunately, has no concept that maps perfectly to them. The nearest analogue of <ahref="https://spec.graphql.org/June2018/#sec-Interfaces">GraphQL interfaces</a> are Rust traits, and the main difference is that in GraphQL an <ahref="https://spec.graphql.org/June2018/#sec-Interfaces">interface type</a> serves both as an <em>abstraction</em> and a <em>boxed value (downcastable to concrete implementers)</em>, while in Rust, a trait is an <em>abstraction only</em> and <em>to represent such a boxed value a separate type is required</em>, like enum or trait object, because Rust trait doesn't represent a type itself, and so can have no values. This difference imposes some unintuitive and non-obvious corner cases when we try to express <ahref="https://spec.graphql.org/June2018/#sec-Interfaces">GraphQL interfaces</a> in Rust, but on the other hand gives you full control over which type is backing your interface, and how it's resolved.</p>
<p>For implementing <ahref="https://spec.graphql.org/June2018/#sec-Interfaces">GraphQL interfaces</a> Juniper provides the <code>#[graphql_interface]</code> macro.</p>
<p>Defining a trait is mandatory for defining a <ahref="https://spec.graphql.org/June2018/#sec-Interfaces">GraphQL interface</a>, because this is the <em>obvious</em> way we describe an <em>abstraction</em> in Rust. All <ahref="https://spec.graphql.org/June2018/#sec-Interfaces">interface</a> fields are defined as computed ones via trait methods.</p>
<p>However, to return values of such <ahref="https://spec.graphql.org/June2018/#sec-Interfaces">interface</a>, we should provide its implementers and the Rust type representing a <em>boxed value of this trait</em>. The last one can be represented in two flavors: enum and <ahref="https://doc.rust-lang.org/reference/types/trait-object.html">trait object</a>.</p>
<p>By default, Juniper generates an enum representing the values of the defined <ahref="https://spec.graphql.org/June2018/#sec-Interfaces">GraphQL interface</a>, and names it straightforwardly, <code>{Interface}Value</code>.</p>
<p>If, for some reason, we would like to use <ahref="https://doc.rust-lang.org/reference/types/trait-object.html">trait objects</a> for representing <ahref="https://spec.graphql.org/June2018/#sec-Interfaces">interface</a> values incorporating dynamic dispatch, then it should be specified explicitly in the trait definition.</p>
<p>Downcasting <ahref="https://doc.rust-lang.org/reference/types/trait-object.html">trait objects</a> in Rust is not that trivial, that's why macro transforms the trait definition slightly, imposing some additional type parameters under-the-hood.</p>
<blockquote>
<p><strong>NOTICE</strong>:<br/>
A <strong>trait has to be <ahref="https://doc.rust-lang.org/stable/reference/items/traits.html#object-safety">object safe</a></strong>, because schema resolvers will need to return a <ahref="https://doc.rust-lang.org/reference/types/trait-object.html">trait object</a> to specify a <ahref="https://spec.graphql.org/June2018/#sec-Interfaces">GraphQL interface</a> behind it.</p>
<p>We may want to omit some trait methods to be assumed as <ahref="https://spec.graphql.org/June2018/#sec-Interfaces">GraphQL interface</a> fields and ignore them.</p>
<aclass="header"href="#fields-arguments-and-interface-customization"id="fields-arguments-and-interface-customization"><h3>Fields, arguments and interface customization</h3></a>
<p>Similarly to <ahref="https://spec.graphql.org/June2018/#sec-Objects">GraphQL objects</a> Juniper allows to fully customize <ahref="https://spec.graphql.org/June2018/#sec-Interfaces">interface</a> fields and their arguments.</p>
<p>Renaming policies for all <ahref="https://spec.graphql.org/June2018/#sec-Interfaces">GraphQL interface</a> fields and arguments are supported as well:</p>
<p>If a <ahref="https://docs.rs/juniper/0.14.2/juniper/trait.Context.html"><code>Context</code></a> is required in a trait method to resolve a <ahref="https://spec.graphql.org/June2018/#sec-Interfaces">GraphQL interface</a> field, specify it as an argument.</p>
<p>If an <ahref="https://docs.rs/juniper/latest/juniper/struct.Executor.html"><code>Executor</code></a> is required in a trait method to resolve a <ahref="https://spec.graphql.org/June2018/#sec-Interfaces">GraphQL interface</a> field, specify it as an argument.</p>
<p>This requires to explicitly parametrize over <ahref="https://docs.rs/juniper/latest/juniper/trait.ScalarValue.html"><code>ScalarValue</code></a>, as <ahref="https://docs.rs/juniper/latest/juniper/struct.Executor.html"><code>Executor</code></a> does so.</p>
<p>By default, the <ahref="https://spec.graphql.org/June2018/#sec-Interfaces">GraphQL interface</a> value is downcast to one of its implementer types via matching the enum variant or downcasting the trait object (if <code>dyn</code> macro argument is used).</p>
<p>However, if some custom logic is needed to downcast a <ahref="https://spec.graphql.org/June2018/#sec-Interfaces">GraphQL interface</a> implementer, you may specify either an external function or a trait method to do so.</p>
<p>By default, <code>#[graphql_interface]</code> macro generates code, which is generic over a <ahref="https://docs.rs/juniper/latest/juniper/trait.ScalarValue.html"><code>ScalarValue</code></a> type. This may introduce a problem when at least one of <ahref="https://spec.graphql.org/June2018/#sec-Interfaces">GraphQL interface</a> implementers is restricted to a concrete <ahref="https://docs.rs/juniper/latest/juniper/trait.ScalarValue.html"><code>ScalarValue</code></a> type in its implementation. To resolve such problem, a concrete <ahref="https://docs.rs/juniper/latest/juniper/trait.ScalarValue.html"><code>ScalarValue</code></a> type should be specified.</p>
