<labelid="sidebar-toggle"class="icon-button"for="sidebar-toggle-anchor"title="Toggle Table of Contents"aria-label="Toggle Table of Contents"aria-controls="sidebar">
<inputtype="search"id="searchbar"name="searchbar"placeholder="Search this book ..."aria-controls="searchresults-outer"aria-describedby="searchresults-header">
<p><ahref="https://spec.graphql.org/October2021#sec-Interfaces">GraphQL interfaces</a> represent a list of named <ahref="https://spec.graphql.org/October2021#sec-Language.Fields">fields</a> and their <ahref="https://spec.graphql.org/October2021#sec-Language.Arguments">arguments</a>. <ahref="https://spec.graphql.org/October2021#sec-Objects">GraphQL objects</a> and <ahref="https://spec.graphql.org/October2021#sec-Interfaces">interfaces</a> can then implement these <ahref="https://spec.graphql.org/October2021#sec-Interfaces">interfaces</a> which requires that the implementing type will define all <ahref="https://spec.graphql.org/October2021#sec-Language.Fields">fields</a> defined by those <ahref="https://spec.graphql.org/October2021#sec-Interfaces">interfaces</a>.</p>
</blockquote>
<p><ahref="https://spec.graphql.org/October2021#sec-Interfaces">GraphQL interfaces</a> map well to interfaces known from common object-oriented languages such as Java or C#, but <ahref="https://www.rust-lang.org">Rust</a>, unfortunately, has no concept that maps perfectly to them. The nearest analogue of <ahref="https://spec.graphql.org/October2021#sec-Interfaces">GraphQL interfaces</a> are <ahref="https://doc.rust-lang.org/reference/items/traits.html#traits">Rust traits</a>, but the main difference is that in <ahref="https://graphql.org">GraphQL</a> an <ahref="https://spec.graphql.org/October2021#sec-Interfaces">interface type</a> serves both as an <em>abstraction</em> and a <em>boxed value (dispatchable to concrete implementers)</em>, while in <ahref="https://www.rust-lang.org">Rust</a>, a <ahref="https://doc.rust-lang.org/reference/items/traits.html#traits">trait</a> is an <em>abstraction only</em>, and <em>to represent such a boxed value a separate type is required</em>, like a <ahref="https://doc.rust-lang.org/reference/types/trait-object.html#trait-objects">trait object</a> or an <ahref="https://doc.rust-lang.org/reference/items/enumerations.html#enumerations">enum</a> consisting of implementer types, because <ahref="https://doc.rust-lang.org/reference/items/traits.html#traits">Rust trait</a> doesn't represent a type itself, and so, can have no values.</p>
<p>Another notable difference is that <ahref="https://spec.graphql.org/October2021#sec-Interfaces">GraphQL interfaces</a> are more like <ahref="https://en.wikipedia.org/wiki/Structural_type_system">structurally-typed</a> contracts: they <em>only declare a list of <ahref="https://spec.graphql.org/October2021#sec-Language.Fields">fields</a></em> a <ahref="https://graphql.org">GraphQL</a> type should already have. <ahref="https://doc.rust-lang.org/reference/items/traits.html#traits">Rust traits</a>, on the other hand, are <ahref="https://en.wikipedia.org/wiki/Type_class">type classes</a>, which don't really care about existing methods, but, rather, <em>require to provide implementations for required methods</em> despite the fact whether the type already has such methods or not. This difference makes the <ahref="https://doc.rust-lang.org/reference/items/implementations.html#trait-implementations">trait implementation</a> not a good fit for expressing a <ahref="https://spec.graphql.org/October2021#sec-Interfaces">GraphQL interface</a> implementation, because <em>we don't really need to implement any <ahref="https://spec.graphql.org/October2021#sec-Language.Fields">fields</a></em>, the <ahref="https://graphql.org">GraphQL</a> type implementing a <ahref="https://spec.graphql.org/October2021#sec-Interfaces">GraphQL interface</a> has those <ahref="https://spec.graphql.org/October2021#sec-Language.Fields">fields</a> already. <em>We only need to check that <ahref="https://spec.graphql.org/October2021#sec-Language.Fields">fields'</a> signatures match</em>.</p>
<p>That's why <ahref="https://docs.rs/juniper">Juniper</a> takes the following approach to represent <ahref="https://spec.graphql.org/October2021#sec-Interfaces">GraphQL interfaces</a>, which consists of two parts:</p>
<ol>
<li>Either a <ahref="https://doc.rust-lang.org/reference/items/structs.html">struct</a>, or a <ahref="https://doc.rust-lang.org/reference/items/traits.html#traits">trait</a> (in case <ahref="https://spec.graphql.org/October2021#sec-Language.Fields">fields</a> have <ahref="https://spec.graphql.org/October2021#sec-Language.Arguments">arguments</a>), which acts only as a blueprint describing the required list of <ahref="https://spec.graphql.org/October2021#sec-Language.Fields">fields</a>, and is not used in runtime at all.</li>
<li>An auto-generated <ahref="https://doc.rust-lang.org/reference/items/enumerations.html#enumerations">enum</a>, representing a dispatchable value-type for the <ahref="https://spec.graphql.org/October2021#sec-Interfaces">GraphQL interfaces</a>, which may be referred and returned by other <ahref="https://spec.graphql.org/October2021#sec-Language.Fields">fields</a>.</li>
<p>This may be done by using either the <ahref="https://docs.rs/juniper/0.16.1/juniper/attr.graphql_interface.html"><code>#[graphql_interface]</code> attribute</a> or the <ahref="https://docs.rs/juniper/0.16.1/juniper/derive.GraphQLInterface.html"><code>#[derive(GraphQLInterface)]</code></a>:</p>
<h3id="interfaces-implementing-other-interfaces"><aclass="header"href="#interfaces-implementing-other-interfaces">Interfaces implementing other interfaces</a></h3>
<p><ahref="https://graphql.org">GraphQL</a> allows implementing <ahref="https://spec.graphql.org/October2021#sec-Interfaces">interfaces</a> on other <ahref="https://spec.graphql.org/October2021#sec-Interfaces">interfaces</a> in addition to <ahref="https://spec.graphql.org/October2021#sec-Objects">objects</a>:</p>
<p><strong>NOTE</strong>: Every <ahref="https://spec.graphql.org/October2021#sec-Interfaces">interface</a> has to specify all other <ahref="https://spec.graphql.org/October2021#sec-Interfaces">interfaces</a>/<ahref="https://spec.graphql.org/October2021#sec-Interfaces">objects</a> it implements or implemented for. Missing one of <code>for = </code> or <code>impl = </code> attribute arguments is a <strong>compile-time error</strong>.</p>
<h3id="subtyping-and-additional-nullable-arguments"><aclass="header"href="#subtyping-and-additional-nullable-arguments">Subtyping and additional <code>null</code>able arguments</a></h3>
<p><ahref="https://graphql.org">GraphQL</a> allows implementers (both <ahref="https://spec.graphql.org/October2021#sec-Objects">objects</a> and other <ahref="https://spec.graphql.org/October2021#sec-Interfaces">interfaces</a>) to return "subtypes" instead of an original value. Basically, this allows to impose additional bounds on the implementation.</p>
<li><ahref="https://spec.graphql.org/October2021#sec-Interfaces">interface</a> implementer instead of an <ahref="https://spec.graphql.org/October2021#sec-Interfaces">interface</a> itself:
<p>These rules are recursively applied, so <code>Vec<Vec<I implements T>></code> is a valid "subtype" of a <code>Option<Vec<Option<Vec<Option<T>>>>></code>.</p>
<p>Also, <ahref="https://graphql.org">GraphQL</a> allows implementers to add <code>null</code>able <ahref="https://spec.graphql.org/October2021#sec-Language.Arguments">field arguments</a>, which aren't present on an original interface.</p>
<p><strong>NOTE</strong>: Violating <ahref="https://graphql.org">GraphQL</a> "subtyping" or additional <code>null</code>able <ahref="https://spec.graphql.org/October2021#sec-Language.Arguments">argument</a> rules is a <strong>compile-time error</strong>.</p>
<p><ahref="objects/complex_fields.html#default-arguments">Similarly to GraphQL object fields</a>, <ahref="https://spec.graphql.org/October2021#sec-Language.Fields">GraphQL arguments</a> of <ahref="https://spec.graphql.org/October2021#sec-Interfaces">interfaces</a> are able to have default values, though <ahref="https://www.rust-lang.org">Rust</a> doesn't have such notion:</p>
<p>Just as with <ahref="objects/index.html#renaming">defining GraphQL objects</a>, by default, <ahref="https://spec.graphql.org/October2021#sec-Language.Fields">fields</a> are converted from <ahref="https://www.rust-lang.org">Rust</a>'s standard <code>snake_case</code> naming convention into <ahref="https://graphql.org">GraphQL</a>'s <code>camelCase</code> convention:</p>
<p>We can override the name by using the <code>#[graphql(name = "...")]</code> attribute:</p>
<p><strong>TIP</strong>: Supported policies are: <code>SCREAMING_SNAKE_CASE</code>, <code>camelCase</code> and <code>none</code> (disables any renaming).</p>
</blockquote>
<h3id="documentation-and-deprecation"><aclass="header"href="#documentation-and-deprecation">Documentation and deprecation</a></h3>
<p>Similarly, <ahref="https://spec.graphql.org/October2021#sec-Language.Fields">GraphQL fields</a> of <ahref="https://spec.graphql.org/October2021#sec-Interfaces">interfaces</a> may also be <ahref="https://spec.graphql.org/October2021#sec-Descriptions">documented</a> and <ahref="https://spec.graphql.org/October2021#sec--deprecated">deprecated</a> via <code>#[graphql(description = "...")]</code> and <code>#[graphql(deprecated = "...")]</code>/<ahref="https://doc.rust-lang.org/reference/attributes/diagnostics.html#the-deprecated-attribute"><code>#[deprecated]</code></a> attributes:</p>
<p><strong>NOTE</strong>: Only <ahref="https://spec.graphql.org/October2021#sec-Interfaces">GraphQL interface</a>/<ahref="https://spec.graphql.org/October2021#sec-Objects">object</a> fields and <ahref="https://spec.graphql.org/October2021#sec-Enums">GraphQL enum</a> values can be <ahref="https://spec.graphql.org/October2021#sec--deprecated">deprecated</a>.</p>
<p>By default, all <ahref="https://doc.rust-lang.org/reference/items/structs.html">struct</a> fields or <ahref="https://doc.rust-lang.org/reference/items/traits.html#traits">trait</a> methods are considered as <ahref="https://spec.graphql.org/October2021#sec-Language.Fields">GraphQL fields</a>. If a helper method is needed, or it should be ignored for some reason, then it should be marked with the <code>#[graphql(ignore)]</code> attribute:</p>
<p><strong>TIP</strong>: See more available features in the API docs of the <ahref="https://docs.rs/juniper/0.16.1/juniper/attr.graphql_interface.html"><code>#[graphql_interface]</code></a> attribute.</p>
