Designing response types

Let's say we have a basic GraphQL API that defines the following Query type:

1
type Query {
2
  users: [User!]!
3
}

This Query.users field makes intuitive sense: if you query it, you get back a list of User objects. However, this return type doesn't provide any insight into the result:

If the list is empty, is that because there are zero users, or did an error occur?
Even if the list is populated, did the API return all users or just a subset?

To answer questions like these, it's helpful for top-level fields of Query and Mutation to return "wrapper" objects that can include both the operation result and metadata about the operation's execution.

Example: `UsersResponse`

The following example defines a UsersResponse type for our Query.users field:

1
enum ResponseStatus {
2
  SUCCESS
3
  FAILURE
4
}
5

6
type User {
7
  id: ID!
8
  firstName: String!
9
  lastName: String!
10
}
11

12
type UsersResponse {
13
  status: ResponseStatus!
14
  total: Int!
15
  users: [User!]!
16
}
17

18
type Query {
19
  users: UsersResponse!
20
}

With this change, a client's query can now check the status field to determine whether an empty list might be due to an error:

1
query FetchUsers {
2
  users {
3
    status
4
    total
5
    users {
6
      id
7
      firstName
8
      lastName
9
    }
10
  }
11
}

Response types for mutations

This response type pattern is even more useful for mutations, because they can result in many valid failure states (such as attempting to delete an object that doesn't exist).

For example, let's say we have an e-commerce graph. When executing a checkout mutation, it's valid for that mutation to fail if a purchased item is out of stock or the buyer has insufficient funds.

If we define a set of ErrorResponse types in our schema, front-end developers can provide customized experiences based on the type of failure that occurred:

1
interface MutationResponse {
2
  status: ResponseStatus!
3
}
4

5
type CheckoutSuccess implements MutationResponse {
6
  status: ResponseStatus!
7
  cart: [Product!]!
8
  invoice: Invoice!
9
}
10

11
interface ErrorResponse {
12
  status: ResponseStatus!
13
  message: String!
14
}
15

16
type CheckoutError implements ErrorResponse {
17
  status: ResponseStatus!
18
  message: String!
19
}
20

21
union CheckoutResponse = CheckoutSuccess | CheckoutError
22

23
type Mutation {
24
  checkout(cart: ID!): CheckoutResponse!
25
}

Home