Polymorphic result fields
A search or feed can return several concrete resource types that share fields such as an identifier and display name.
GraphQL · Class
GraphQLInterfaceType
A GraphQL interface is an abstract type that declares fields shared by concrete object types or other interfaces. It lets a field return different implementing types while clients query their common fields.
How it works
An interface defines shared fields for multiple concrete object types. A field returning an interface can produce any implementing object, while clients can request the shared fields and use inline fragments for type-specific fields.
Syntax
interface Character {
id: ID!
name: String!
}Key points
- Interfaces are abstract GraphQL types rather than directly instantiated concrete objects.
- An interface is one of GraphQL's abstract type categories.
- The interface declaration establishes the shared field contract.
- Concrete objects and other interfaces can implement it only by including the declared fields.
- Interfaces communicate common behavior across otherwise different types.
Common mistakes
- Use an interface for polymorphic results; a returned value may be one of several concrete object types.
Example: An interface and an implementing object
interface Character {
id: ID!
name: String!
friends: [Character]
appearsIn: [Episode]!
}
type Human implements Character {
id: ID!
name: String!
friends: [Character]
appearsIn: [Episode]!
homePlanet: String
}This schema lets a field return different concrete character types while clients request the shared Character fields.
When to use it
Shared domain contract
Several domain objects expose the same required behavior while retaining their own additional fields.
Common and specialized selections
A client needs common fields from multiple implementations and optional type-specific fields through fragments.
Interview questions
QWhat problem do GraphQL interfaces solve?
An interface is an abstract type that declares fields shared by multiple concrete object types. Each object that implements it must include those fields, so a field returning the interface can return different implementing objects.
Follow-up: How can a client request fields that exist only on one implementation? Use an inline fragment conditioned on that concrete type.
QWhen would you choose an interface?
Interfaces are useful when one field should return objects of several types while exposing a common selection set. The schema guarantees that implementing object types provide the interface's declared fields.
Follow-up: What should a client do when an interface gains a new implementation? Query __typename and handle unknown runtime types without crashing.
QHow are interface-specific fields queried?
Clients can query fields declared by the interface directly. For implementation-specific fields, they use inline fragments for the relevant concrete object type.
Follow-up: How does a client discover the available implementations? Introspection can reveal which object types implement an interface.
Related
Object typesUnion typesInline fragmentsIntrospection__typename