Interface vs Union in GraphQL schema design

Question

Suppose I am building a GraphQL API that serves a timeline of natural disaster events.

There are two different kinds of event right now:

• Hurricane
• Earthquake

All events have an ID and a date they occurred. I plan to have a paginated query for fetching events using cursors.

I can think of 2 different approaches to modelling my domain.

1. Interface

interface Event {
  id: ID!
  occurred: String! # ISO timestamp
}

type Earthquake implements Event {
  epicenter: String!
  magnitude: Int!
}

type Hurricane implements Event {
  force: Int!
}

2. Union

type Earthquake {
  epicenter: String!
  magnitude: Int!
}

type Hurricane {
  force: Int!
}

type EventPayload = 
  | Earthquake
  | Hurricane

type Event {
  id: ID!
  occurred: String! # ISO timestamp
  payload: EventPayload!
}

What are the trade-offs between the two approaches?

Answer 1

I believe that:

• unions are about providing: a field / its resolver function resolves with an object, whose type belongs to a specific, known, set of types.
• interfaces are about requesting: without, the clients would have to repeat the fields they are interested in, in every type fragment.

They serve different purposes, and they can be used together:

interface I {
    id: ID!
}

type A implements I {
    id: ID!
    a: Int!
}

type B implements I {
    id: ID!
    b: Int!
}

type C implements I {
    id: ID!
    c: Int!
}

union Foo = A | C

type Query {
    foo: Foo!
}

This schema declares that A, B, and C have some fields in common, so that it's easier for the client to request them, and that querying foo can only yield A or C.

Could you write foo: I! instead? While this would work seamlessly, I believe this leads to a bad development experience. If you're saying that foo provides an I object, your clients should be prepared for receiving any of the implementing types, including B, and would spend time to write and maintain a code that will never be called. If you know that foo can only yield A and C, please tell them explicitly.

The same holds if foo were to yield A, B, or C. It happens that it's exactly the list of types that implement I, so in this case, could you write foo: I!? No! Don't be fooled by that. Why? Because this list is expandable through federation / schema stitching! I believe it's a seldom used feature of some GraphQL frameworks, but whose adoption grows. If you've never used it, please try, it will open your mind to new ideas of inter-micro-service-communication and other Medium buzzwords. In short, imagine you're making a public API, or even somewhat-public within an organization. Someone else could "augment" your API by providing extra stuff. This may include new types implementing your interface. And so we're back to the previous paragraph.

So far, it looks like I'm in favor of your first code.

However, and this may be specific to this scenario, it seems to me that your definition of event mixes both data about its occurrence and about physics metrics. Your second code splits them into two type hierarchy. I like that. It feels more architecture-friendly. Your schema is more open. Imagine your API is about event history, and someone enhance it with forecasts: your EventPayload can be reused!

Besides, note that your first example is incomplete. Types implementing an interface must implement, i.e. repeat, every single field of this interface, like I wrote in the above code. This becomes harder to maintain as the number of fields and the number of implementing types grow.

So, the second solution also has some advantages. But doing so, the blah-blah I made earlier about being specific with returned types is hard to implement, because the payload, which is the one to be specific about, is embedded into another type, and there's no such thing as generics in GraphQL.

Here's a proposal to reconcile all of that:

interface HasForce {
    force: Int!
}

type Earthquake {
    epicenter: String!
    magnitude: Int!
}

type Hurricane implements HasForce {
    force: Int!
}

type Tsunami implements HasForce {
    force: Int!
}

interface Event {
    data: EventData!
}

type EventData {
    id: ID!
    occurred: String!
}

union HistoryMeteorologicalPhenomenon = Earthquake | Hurricane

type HistoryEvent implements Event {
    data: EventData!
    meteorologicalPhenomenon: HistoryMeteorologicalPhenomenon!
}

type Query {
    historyEvents: [HistoryEvent!]!
}

It looks a bit more complex that both of your proposals, but it fulfills my needs. Also, it's rare to look at a schema from this height: more often, we know the entry point and dig down from there. For instance, I open the documentation at historyEvents, see that it yields phenomena of two kinds, fine, I'm not aware that other union types and event types exist.

If you were to write a lot of these union + event pairs, you could generate them with code instead, whereby one function call would declare a pair. Less error-prone, funnier to implement, and with more potential of Medium articles.

Note that the GraphQL structure is independent of your storage structure. It's possible to have multiple GraphQL objects providing data from the same insert-your-language-here object, e.g. yielded by your DB driver. There may be a tiny overhead that I haven't benchmarked, but providing a cleaner API outweighs that to me. The basic idea is that resolver functions just have to resolve with the same source, so that the resolver functions related to another type will be called with the same source object.