Is it possible to deprecate a mutation on GraphQL?

Question

I have a mutation that we want to deprecate:

updateObject(
  id: String!
  object: ObjectInput!
): Object!

We'd like to change it to:

updateObject(
  object: UpdateObjectInput!
): Object!

Where ObjectInput and UpdateObjectInput are:

input ObjectInput {
  product: String!
  isPercentage: Boolean
  amount: Float!
  visibility: ObjectVisibility
  isDiscontinued: Boolean
  expiresAt: String
}

and

input UpdateObjectInput {
  id: String!
  visibility: ObjectVisibility
  isDiscontinued: Boolean
  expiresAt: String
}

Basically, ObjectInput is great for creating Object, but not ideal for updating it.

We've tried overloading the mutation or marking the mutation as deprecated, but neither works.

The only other solutions we've come up with is to rename the new updateObject mutation to something else, like "newUpdateObject", or to make the id and object fields deprecated and optional and then add a field "updateObject" or something that would take in the new UpdateObjectInput. However, neither of those is optimal.

Is there another way to accomplish the migration?

Answer 1

Deprecating a field is cosmetic -- it just introduces metadata that can be used by client tools and can provide additional information about the field without changing the field's description. When a change to the schema would otherwise be a breaking change, the only way to avoid causing issues for your clients is to introduce new fields and/or arguments. You've already presented some of your options:

1. Create a new field on the Mutation type

updateObject(
  id: String!
  object: ObjectInput!
): Object! @deprecated("Use updateObject2 instead")
updateObject2(
  object: UpdateObjectInput!
): Object!

2. Create a new argument on the existing field. ONly fields and enum values can be deprecated at this time -- you can't apply the @deprecated to arguments.

updateObject(
  """Don't use. Use object2 instead"""
  id: String!

  """Don't use. Use object2 instead"""
  object: ObjectInput!

  object2: UpdateObjectInput!
): Object!

3. Version the API. Maintain the existing schema at its current endpoint, but introduce the updated schema at a different endpoint. Direct your client team(s) to switch to the new endpoint.

4. Just introduce the breaking changes. It may be possible to coordinate with the client team(s) to deploy the changes to both the server and the client within some acceptable maintenance window.