---
stage: none
group: unassigned
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments
---

# GraphQL API merge request checklist

The GitLab GraphQL API has a fair degree of complexity so it's important that merge requests containing GraphQL changes be reviewed by someone familiar with GraphQL.
You can ping one via the `@gitlab-org/graphql-experts` group in a MR or in the [`#f_graphql` channel](https://gitlab.slack.com/archives/C6MLS3XEU) in Slack (available to GitLab team members only).

GraphQL queries need to be reviewed for:

- breaking changes
- authorization
- performance

## Review criteria

This is not an exhaustive list.

### Description with sample query

Ensure that the description includes a sample query with setup instructions.
Try running the query in [GraphiQL](../api_graphql_styleguide.md#graphiql) on your local GDK instance.

### No breaking changes (unless after full deprecation cycle)

Check the MR for any [breaking changes](../api_graphql_styleguide.md#breaking-changes).

If a feature is marked as an [Experiment](../api_graphql_styleguide.md#mark-schema-items-as-alpha), you can make breaking changes immediately, with no deprecation period.

For more information, see [deprecation and removal process](../../api/graphql/index.md#deprecation-and-removal-process).

### Multiversion compatibility

Ensure that multi-version compatibility is guaranteed.
This generally means frontend and backend code for the same GraphQL feature can't be shipped in the same release.

For details, see [multiple version compatibility](../multi_version_compatibility.md).

### Technical writing review

Changes to the generated API docs require a technical writer review.

### Changelog

Public-facing changes that are not marked as an [Experiment](../api_graphql_styleguide.md#mark-schema-items-as-alpha) require a [changelog entry](../changelog.md).

### Use the framework

GraphQL is a framework with many moving parts. It's important that the framework is followed.

- Do not manually invoke framework bits. For example, do not instantiate resolvers during execution and instead let the framework do that.
- You can subclass resolvers, as in `MyResolver.single` (see [deriving resolvers](../api_graphql_styleguide.md#deriving-resolvers)).
- Use the `ready?` method for more complex argument logic (see [correct use of resolver#ready](../api_graphql_styleguide.md#correct-use-of-resolverready)).
- Use the `prepare` method for more complex argument validation (see [validating arguments](../api_graphql_styleguide.md#validating-arguments)).

For details, see [resolver guide](../api_graphql_styleguide.md#writing-resolvers).

### Authorization

Ensure proper authorization is followed and that `authorize :some_ability` is tested in the specs.

For details, see [authorization guide](authorization.md).

### Performance

Ensure:

- You avoid N+1s with [BatchLoader](batchloader.md) or [Lookahead](../api_graphql_styleguide.md#look-ahead) when appropriate.
- You use [laziness](../api_graphql_styleguide.md#laziness) appropriately.

### Use appropriate types

For example:

- [`TimeType`](../api_graphql_styleguide.md#typestimetype) for Ruby `Time` and `DateTime` objects.
- Global IDs for `id` fields

For details, see [types](../api_graphql_styleguide.md#types).

### Appropriate complexity

Query complexity is a way of quantifying how expensive a query is likely to be. Query complexity limits are defined as constants in the schema.
When a resolver or type is expensive to call we need to ensure that the query complexity reflects that.

For details, see [max complexity](../api_graphql_styleguide.md#max-complexity), [field complexity](../api_graphql_styleguide.md#field-complexity) and [query limits](../api_graphql_styleguide.md#query-limits).

### Testing

- Resolver (unit) specs are deprecated in favour of request (integration) specs.
- Many aspects of our framework are outside the `resolve` method and a request spec is the only way to ensure they behave properly.
- Every GraphQL change MR should ideally have changes to API specs.

For details, see [testing guide](../api_graphql_styleguide.md#testing).