Interfaces in GraphQL Schema

GraphQL is a powerful open-source query language for APIs. It is known for its flexibility and efficiency in fetching data from server endpoints. Unlike traditional REST APIs, which often have multiple endpoints for different resources, GraphQL typically exposes a single endpoint that allows clients to request exactly the data they need.

Interfaces in GraphQL help create a common set of fields and types that can be reused by other types or Queries. In this article, we will learn about the interfaces in GraphQL Schema.

Understanding GraphQL Interfaces

An interface in GraphQL acts as a blueprint for a collection of fields and types, that can be reused by some other field or types in a GraphQL query. With its help, we can define some common set of interfaces, and use those in our actual schema to abstract out our business logic, and give our schema greater flexibility.

Defining Interfaces in GraphQL Schema

We define an interface with the help of the “interface” keyword in a GraphQL Schema, followed by an interface name, and the fields that we want to list out and be represented by it.

Example –

In the below example, we will create an Animal interface, which is a collection of ID, name, and species fields. This interface is then used by other interfaces, Dog and Cat, to inherit all the fields of the Animal interface, with some additional fields of their own.

 interface Animal {
  id: ID!
  name: String!
  species: String!
}

type Dog implements Animal {
  id: ID!
  name: String!
  species: String!
  breed: String!
}

type Cat implements Animal {
  id: ID!
  name: String!
  species: String!
  color: String!
}

Querying Interface Fields

We will look at how we can query interface fields directly from a GraphQL API, and how the server will return the appropriate fields based on the type of the queried object.

For the below example, we will use the following GraphQL playground to query the API from.

GraphQL playground –

https://studio.apollographql.com/public/countries/variant/current/explorer

Example –

In the below example, we will query the common fields such as name, and country, and will use inline fragments to query the specific field, native from the Country interface.

query {
  country(code: "BR") {
    name
    currency
    ... on Country {
      native
    }
  }
}

Output:

Implementing Interfaces in Mutations

We can implement interfaces in the mutations itself where the mutations require an input object to be passed in its argument. With the interface as its type, the input object will be expected to have the same types as its interface.

type Mutation {
  addUser(input: AddUserInput!): User!
}

input AddUserInput {
  name: String!
  age: Int!
}

In the above example, addUser mutation accepts an input object that should have interface of AddUserInput. This implies that the input object will have all the fields of the interface.

Handling Interfaces in Resolvers

Interfaces can be used inside the GraphQL resolvers as well to resolve their fields dynamically based on a specific condition or the concrete type of the return object. Let’s look at a simplified example below –

In the below interface example, we have an interface Shape, with a findArea field inside it. We have 2 types derived from the interface, namely “Circle” and “Square”.

interface Shape {
  findArea: Float!
}

type Circle implements Shape {
  radius: Float!
  findArea: Float!
}

type Square implements Shape {
  length: Float!
  findArea: Float!
}

Now, while defining the resolvers for the “findArea” field, we will define “__resolveType” function on the Shape interface, and based on the availability of specific fields inside the type, like “radius” or “length”, we will define the resolvers for the “findArea” for each of the concrete types, “Circle” and “Square”.

const resolvers = {
  Shape: {
    __resolveType(shape) {
      if (shape.radius) {
        return 'Circle';
      }
      if (shape.length) {
        return 'Square';
      }
      return null;
    },
  },
  Circle: {
    findArea(circle) {
      return Math.PI * circle.radius * circle.radius;
    },
  },
  Square: {
    findArea(square) {
      return square.length * square.length;
    },
  },
};

Conclusion

In this article, we learnt about interfaces in GraphQL Schema, and how we can use it to create a common definition of certain fields that can we reused by other fields in a GraphQL query. We also looked at some examples, and saw how we can use interfaces in a GraphQL query. Interfaces help enhance flexibility of the schema, and allow reuse of common fields that are frequently used in other places.