Comments starting with #!
in schema.graphql will be stripped out before the GraphQL documentation is generated. #!
is useful for implementation details and security notes that shouldn't be displayed to API users.
When changing the GraphQL schema, try to make changes that cause the API to "grow", such as:
String!
)Avoid "shrinking" the API with changes such as:
Because most queries do not mention return types directly, it's often possible to change the return type of a field as long as the new return type is a superclass of the old one. This breaks when clients use __typename
, for example to determine the union variant of a value, so use caution when changing this.
As an example of changing a return type, imagine this query that deletes a user by ID:
mutation { deleteUser(id: 1) { alwaysNil } }
Let's say we want to return the User
that was deleted by deleteUser
, but it's currently returning EmptyResponse
. We could change the return type to User
and temporarily add the alwaysNil
field to User
while clients migrate:
type Mutation { - deleteUser(id: ID!): EmptyResponse + deleteUser(id: ID!): User! } type EmptyResponse { alwaysNil: String } type User { ... id: ID! + # For compatibility with old clients only. + alwaysNil: String }
When the new type is not a superclass of the old one (e.g. String
-> User
), a breaking change is required.
Try to avoid making breaking changes, but if you have to, be sure to give clients time to migrate. This usually involves splitting the change into 2 parts. For example, if you want to rename a field in the return type of a query: