GraphQL Interface Types — Defining Shared Fields Across Multiple Object Types

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

GraphQL interface types define a set of common fields that multiple object types can implement, enabling polymorphic queries where a field can return different types that share a common structure.

What You'll Learn

• Defining interfaces with shared fields
• Implementing interfaces on object types
• Querying interfaces with inline fragments

Why It Matters

Interfaces reduce schema duplication and enable flexible queries that return different types. Without interfaces, you cannot query common fields across different object types.

Code Examples

# Interface definition
interface Node {
  id: ID!
  createdAt: DateTime!
  updatedAt: DateTime!
}

interface Media {
  id: ID!
  url: String!
  width: Int!
  height: Int!
  fileSize: Int!
}

# Types implementing interfaces
type User implements Node {
  id: ID!
  createdAt: DateTime!
  updatedAt: DateTime!
  name: String!
  email: String!
}

type Post implements Node {
  id: ID!
  createdAt: DateTime!
  updatedAt: DateTime!
  title: String!
  content: String!
  author: User!
}

type Image implements Node & Media {
  id: ID!
  createdAt: DateTime!
  updatedAt: DateTime!
  url: String!
  width: Int!
  height: Int!
  fileSize: Int!
  alt: String!
}

type Video implements Node & Media {
  id: ID!
  createdAt: DateTime!
  updatedAt: DateTime!
  url: String!
  width: Int!
  height: Int!
  fileSize: Int!
  duration: Int!
  format: String!
}

# Querying interfaces with inline fragments
query {
  search(term: "graphql") {
    ... on User {
      name
      email
    }
    ... on Post {
      title
      content
    }
    ... on Media {
      url
      width
      height
    }
  }
}

// Interface resolvers
const typeDefs = `
  interface Node {
    id: ID!
    createdAt: String!
  }

  type User implements Node {
    id: ID!
    createdAt: String!
    name: String!
  }
`;

const resolvers = {
  Node: {
    __resolveType(parent) {
      // Return the type name based on the parent object
      if (parent.name) return 'User';
      if (parent.title) return 'Post';
      return null;
    }
  }
};

Common Mistakes

1. Making Interfaces Too Specific

Interfaces should contain only truly common fields. Type-specific fields belong on the implementing type.

2. Not Implementing __resolveType

Without __resolveType, the server cannot determine which concrete type to return.

3. Overusing Interfaces for Unrelated Types

Interfaces imply a relationship. Do not force unrelated types to share an interface.

4. Forgetting All Required Fields in Implementations

Implementing types must include all interface fields with matching types.

5. Nesting Interfaces Too Deeply

Avoid deeply nested interface hierarchies. Keep interface inheritance flat.

Practice Questions

1. What is the purpose of interfaces in GraphQL?
2. How do you implement an interface on an object type?
3. What does __resolveType do?
4. How do you query type-specific fields on an interface?
5. Can a type implement multiple interfaces?

Answers:

1. To define common fields that multiple object types must implement.
2. Use the implements keyword: type User implements Node { ... }.
3. It tells GraphQL which concrete type to return when a field returns an interface type.
4. Use inline fragments with ... on TypeName.
5. Yes, separate multiple interfaces with &: type Image implements Node & Media.

Challenge: Design a content management schema with interfaces for Content (common fields), Media (images, videos, documents), and Commentable (content that supports comments). Implement at least 5 types across these interfaces.

FAQ

Mini Project

Build a notification system schema with a Notification interface and implementing types: EmailNotification, PushNotification, SMSNotification, InAppNotification. Include common fields (id, message, status, createdAt) and type-specific fields. Write queries using inline fragments.

What's Next

Explore union types for polymorphic responses without shared fields, then learn about input types for mutation arguments.