Index · Graphql · Api

Introduced in GitLab 11.0 (enabled by feature flag graphql).
Always enabled in GitLab 12.1.

Getting Started

For those new to the GitLab GraphQL API, seeGetting started with GitLab GraphQL API.

Quick Reference

The GitLab GraphQL API endpoint is located at /api/graphql.
Get an introduction to GraphQL from graphql.org.
GitLab supports a wide range of resources, listed in the GraphQL API Reference.

Examples

To work with sample queries that pull data from public projects on GitLab.com,see the menu options in the left-handdocumentation menu, under API > GraphQL at https://docs.gitlab.com/ee/api/graphql/.

The Getting started page includes different methods to customize GraphQL queries.

GraphiQL

Explore the GraphQL API using the interactive GraphiQL explorer,or on your self-managed GitLab instance onhttps://<your-gitlab-site.com>/-/graphql-explorer.

See the GitLab GraphQL overview for more information about the GraphiQL Explorer.

What is GraphQL?

GraphQL is a query language for APIs thatallows clients to request exactly the data they need, making itpossible to get all required data in a limited number of requests.

The GraphQL data (fields) can be described in the form of types,allowing clients to use client-side GraphQLlibraries to consume theAPI and avoid manual parsing.

Since there's no fixed endpoints and data model, new abilities can beadded to the API without creating breaking changes. This allows us tohave a versionless API as described in the GraphQLdocumentation.

Vision

We want the GraphQL API to be the primary means of interactingprogrammatically with GitLab. To achieve this, it needs full coverage - anythingpossible in the REST API should also be possible in the GraphQL API.

To help us meet this vision, the frontend should use GraphQL in preference tothe REST API for new features.

There are no plans to deprecate the REST API. To reduce the technical burden ofsupporting two APIs in parallel, they should share implementations as much aspossible.

Breaking changes

The GitLab GraphQL API is versionless andchanges are made to the API in a way that maintains backwards-compatibility.

Occasionally GitLab needs to change the GraphQL API in a way that is not backwards-compatible.These changes include the removal or renaming of fields, arguments or other parts of the schema.

In these situations, GitLab follows a Deprecation and removal processwhere the deprecated part of the schema is supported for a period of time before being removed.

There are some changes which are explicitly not considered breaking.

Clients should familiarize themselves with the process to avoid breaking changes affecting their integrations.

WARNING:While GitLab will make all attempts to follow the deprecation and removal process,GitLab may on very rare occasions need to make immediate breaking changes to the GraphQL API to patch critical security or performanceconcerns and where the deprecation process would be considered to pose significant risk.

NOTE:Fields behind a feature flag and disabled by default are exempt from the deprecation process,and can be removed at any time without notice.

Deprecation and Removal process

Parts of the schema marked for removal from the GitLab GraphQL API are first deprecated but still availablefor at least six releases, and then removed entirely.Removals occur at X.0 and X.6 releases.

The process is as follows:

The item is marked as deprecated in the schema. It will be displayed as deprecated in theGraphQL API Reference and in introspection queries.
Removals are announced at least one release prior in the Deprecationssection of the release post (at or prior to X.11 and X.5 releases).
Items meeting criteria are removed in X.0 or X.6 and added to:
- The Removals section of the Release Post.
- The Removed items page.

This gives consumers of the GraphQL API a minimum of six months to update their GraphQL queries.

When an item is deprecated or removed, an alternative is provided if available.

Example:

A field marked as deprecated in 12.7 can be used until its removal in 13.6.

List of removed items

View the fields, enums, and other items we removed from the GraphQL API.

Available queries

The GraphQL API includes the following queries at the root level:

project : Project information, with many of its associations such as issues and merge requests.
group : Basic group information and epics (ULTIMATE) are currently supported.
user : Information about a particular user.
namespace : Within a namespace it is also possible to fetch projects.
currentUser: Information about the currently logged in user.
users: Information about a collection of users.
metaData: Metadata about GitLab and the GraphQL API.
snippets: Snippets visible to the currently logged in user.

New associations and root level objects are constantly being added.See the GraphQL API Reference for up-to-date information.

Root-level queries are defined inapp/graphql/types/query_type.rb.

Multiplex queries

GitLab supports batching queries into a single request usingapollo-link-batch-http. Moreinformation about multiplexed queries is also available forGraphQL Ruby, thelibrary GitLab uses on the backend.

Limits

The following limits apply to the GitLab GraphQL API.

Max page size

By default, connections return at most 100 records ("nodes") per page,and this limit applies to most connections in the API. Particular connectionsmay have different max page size limits that are higher or lower.

Max query complexity

The GitLab GraphQL API scores the complexity of a query. Generally, largerqueries will have a higher complexity score. This limit is designed to protectthe API from performing queries that could negatively impact its overall performance.

The complexity of a single query is limited to a maximum of:

200 for unauthenticated requests.
250 for authenticated requests.

The complexity score of a query and limit for the request can be queried for.

If a query exceeds the complexity limit an error message response willbe returned.

In general, each field in a query will add 1 to the complexity score, althoughthis can be higher or lower for particular fields. Sometimes the addition ofcertain arguments may also increase the complexity of a query.

NOTE:The complexity limits may be revised in future, and additionally, the complexityof a query may be altered.

Request timeout

Requests time out at 30 seconds.

Spam

GraphQL mutations can be detected as spam. If this happens, aGraphQL top-level error is raised. For example:

{ "errors": [ { "message": "Request denied. Spam detected", "locations": [ { "line": 6, "column": 7 } ], "path": [ "updateSnippet" ], "extensions": { "spam": true } } ], "data": { "updateSnippet": { "snippet": null } }}

If mutation is detected as potential spam and a CAPTCHA service is configured:

The captchaSiteKey should be used to obtain a CAPTCHA response value using the appropriate CAPTCHA API.Only Google reCAPTCHA v2 is supported.
The request can be resubmitted with the X-GitLab-Captcha-Response and X-GitLab-Spam-Log-Id headers set.

{ "errors": [ { "message": "Request denied. Solve CAPTCHA challenge and retry", "locations": [ { "line": 6, "column": 7 } ], "path": [ "updateSnippet" ], "extensions": { "needsCaptchaResponse": true, "captchaSiteKey": "6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXji*zKhI", "spamLogId": 67 } } ], "data": { "updateSnippet": { "snippet": null, } }}

Reference

The GitLab GraphQL reference is available.

It is automatically generated from the GitLab GraphQL schema and embedded in a Markdown file.

Generate updates for documentation

If you've changed the GraphQL schema, you should set up an MR to gain approval of your changes.To generate the required documentation and schema, follow the instructions given in theRake tasks for developers page.

Be sure to run these commands using the GitLab Development Kit.

Index · Graphql · Api · Help (2024)