Interfaces and Unions in GraphQL

In this tutorial, you will learn about Interfaces and Unions in Graphql. We cover key concepts, practical examples, and best practices to help you master this topic.

Interfaces and unions enable polymorphic types in GraphQL. An interface specifies shared fields that implementing types must include. A union groups distinct types without requiring shared fields. Both use inline fragments for field selection.

What You'll Learn

• Defining interfaces with shared fields
• Implementing interfaces on object types
• Union types for unrelated type groupings
• Inline fragments for type-specific field access
• __typename meta field usage

Why It Matters

Interfaces and unions reduce duplication in schemas and enable flexible query patterns. They model real-world polymorphism like media content, payment methods, or notification types.

Real-World Use

GitHub's search result type uses a union of Repository, Issue, PullRequest, and User. The timeline items on an issue use an interface with types for comments, cross-references, and state changes.

flowchart TD
    Interface[Interface: Media] --> Book[Book]
    Interface --> Video[Video]
    Interface --> Podcast[Podcast]
    Union[Union: SearchResult] --> Product[Product]
    Union --> Article[Article]
    Union --> User[User]

Teacher Mindset

Use interfaces when types share a common set of fields. Use unions when types are completely different but need to appear in the same field. The __typename field always tells clients which concrete type they received.

Code Examples

# Example 1: Interface definition and implementation
interface Media {
  id: ID!
  title: String!
  createdAt: Date!
  author: Author!
}

type Book implements Media {
  id: ID!
  title: String!
  createdAt: Date!
  author: Author!
  isbn: String!
  pageCount: Int!
}

type Video implements Media {
  id: ID!
  title: String!
  createdAt: Date!
  author: Author!
  duration: Int!
  resolution: String!
}

# Example 2: Union type
union SearchResult = Book | Author | Review

type Query {
  search(term: String!): [SearchResult!]!
}

# Example 3: Querying interfaces and unions with inline fragments
query GetFeed {
  media {
    ... on Media {
      id
      title
    }
    ... on Book {
      isbn
      pageCount
    }
    ... on Video {
      duration
      resolution
    }
  }
  search(term: "graphql") {
    __typename
    ... on Book { title author { name } }
    ... on Author { name books { title } }
    ... on Review { rating body }
  }
}

Common Mistakes

• Adding type-specific fields to the interface instead of using implementing types
• Using unions when the types share common fields and an interface would work
• Not querying __typename for client-side type discrimination
• Creating interfaces with too many optional fields that most types leave empty
• Forgetting to include all interface fields in implementing types

Practice

1. Define an interface Notification with shared fields and two implementing types.
2. Create a union PaymentMethod for CreditCard, PayPal, and Crypto types.
3. Write a query that fetches a feed of mixed types using inline fragments.
4. Use __typename to identify the concrete type in a query response.
5. Challenge: Design a schema for a content management system with a Content interface and five implementing types.

FAQ

Mini Project

Refactor your media library schema to use a Media interface with Book, Audiobook, and Podcast implementing types. Add a SearchResult union for cross-entity search.

What's Next

Next, you will learn about GraphQL error handling patterns for returning structured error information to clients.