@@ -20,6 +20,19 @@ There are no fixed endpoints and no data model, so you can add
to the API without creating [breaking changes](../../development/contributing/#breaking-changes).
This enables us to have a [versionless API](https://graphql.org/learn/best-practices/#versioning).
## Vision
We want the GraphQL API to be the **primary** means of interacting
programmatically with GitLab. To achieve this, it needs full coverage - anything
possible 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 to
the REST API for new features.
There are no plans to deprecate the REST API. To reduce the technical burden of
supporting two APIs in parallel, they should share implementations as much as
possible.
## Work with GraphQL
If you're new to the GitLab GraphQL API, see [Get started with GitLab GraphQL API](getting_started.md).
...
...
@@ -57,72 +70,60 @@ To generate the required documentation and schema, see
Run the commands using the [GitLab Development Kit](https://gitlab.com/gitlab-org/gitlab-development-kit/).
## Vision
We want the GraphQL API to be the **primary** means of interacting
programmatically with GitLab. To achieve this, it needs full coverage - anything
possible 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 to
the REST API for new features.
There are no plans to deprecate the REST API. To reduce the technical burden of
supporting two APIs in parallel, they should share implementations as much as
possible.
## Breaking changes
The GitLab GraphQL API is [versionless](https://graphql.org/learn/best-practices/#versioning) and
changes are made to the API in a way that maintains backwards-compatibility.
The GitLab GraphQL API is [versionless](https://graphql.org/learn/best-practices/#versioning) and changes to the API are primarily backward-compatible.
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.
However, GitLab sometimes changes the GraphQL API in a way that is not backward-compatible. These changes are considered breaking changes, and
can include removing or renaming fields, arguments, or other parts of the schema.
When creating a breaking change, GitLab follows a [deprecation and removal process](#deprecation-and-removal-process).
In these situations, GitLab follows a [Deprecation and removal process](#deprecation-and-removal-process)
where the deprecated part of the schema is supported for a period of time before being removed.
Learn more about [breaking changes](../../development/contributing/#breaking-changes).
There are some changes which are explicitly [not considered breaking](../../development/contributing/#breaking-changes).
Fields behind a feature flag and disabled by default do not follow the deprecation and removal process, and can be removed at any time without notice.
Clients should familiarize themselves with the process to avoid breaking changes affecting their integrations.
To avoid having a breaking change affect your integrations, you should
familiarize yourself with the deprecation and removal process.
WARNING:
While GitLab will make all attempts to follow the [deprecation and removal process](#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 performance
concerns and where the deprecation process would be considered to pose significant risk.
GitLab makes all attempts to follow the [deprecation and removal process](#deprecation-and-removal-process).
On rare occasions, GitLab might make immediate breaking changes to the GraphQL
API to patch critical security or performance concerns if the deprecation
process would 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
### Deprecation and removal process
The deprecation and removal process for the GitLab GraphQL API aligns with the wider GitLab
Parts of the schema marked for removal from the GitLab GraphQL API are first [deprecated](https://about.gitlab.com/handbook/product/gitlab-the-product/#deprecation) but still available
for at least six releases, and then [removed](https://about.gitlab.com/handbook/product/gitlab-the-product/#removal) entirely. Removals occur on `XX.0` major releases.
Parts of the schema marked for removal from the GitLab GraphQL API are first
but still available for at least six releases. They are then [removed](https://about.gitlab.com/handbook/product/gitlab-the-product/#removal)
entirely during the next `XX.0` major release.
Items are marked as deprecated [in the schema](https://spec.graphql.org/October2021/#sec--deprecated),
and are also displayed as deprecated in:
Items are marked as deprecated in:
- The [schema](https://spec.graphql.org/October2021/#sec--deprecated).
- The [GraphQL API reference](reference/index.md).
- The [deprecation feature removal schedule](../../update/deprecations.md), which is linked to in release posts.
- The [deprecation feature removal schedule](../../update/deprecations.md), which is linked from release posts.
- Introspection queries of the GraphQL API.
NOTE:
Consumers of the GraphQL API are encouraged to remove the use of deprecated schema in their GraphQL
If you use the GraphQL API, we recommend you remove the deprecated schema from your GraphQL
API calls as soon as possible to avoid experiencing breaking changes.
If an alternative is provided for the deprecated schema item, then its deprecation message mentions this.
The deprecation message provides an alternative for the deprecated schema item,
if applicable.
**Example:**
#### Deprecation example
The following fields could both be removed in `14.0`:
The following fields are deprecated in different minor releases, but both
removed in GitLab 14.0:
| Field deprecated in | Reason |
| --- | --- |
| `12.7` | As GitLab traditionally has 12 minor releases per major release, the next major release that occurs 6 months after the field was deprecated is `14.0`, rather than `13.0`. |
| `13.6` | The removal in `14.0` allows for 6 months of deprecation. |
| ------------------- | --- |
| 12.7 | GitLab traditionally has 12 minor releases per major release. To ensure the field is available for 6 more releases, it is removed in the 14.0 major release (and not 13.0). |
| 13.6 | The removal in 14.0 allows for 6 months of availability. |
### List of removed items
...
...
@@ -132,16 +133,18 @@ View the [list of items removed](removed_items.md) in previous releases.
The GraphQL API includes the following queries at the root level:
1.`project` : Project information, with many of its associations such as issues and merge requests.
1.`group` : Basic group information and epics **(ULTIMATE)** are currently supported.
1.`user` : Information about a particular user.
1.`namespace` : Within a namespace it is also possible to fetch `projects`.
1.`currentUser`: Information about the currently logged in user.
1.`users`: Information about a collection of users.
1.`metaData`: Metadata about GitLab and the GraphQL API.
1.`snippets`: Snippets visible to the currently logged in user.
New associations and root level objects are constantly being added.
Query | Description
--------------|------------
`project` | Project information and many of its associations, such as issues and merge requests.
`group` | Basic group information and epics.
`user` | Information about a particular user.
`namespace` | The namespace and the `projects` in it.
`currentUser` | Information about the signed-in user.
`users` | Information about a collection of users.
`metaData` | Metadata about GitLab and the GraphQL API.
`snippets` | Snippets visible to the signed-in user.
New associations and root level objects are regularly added.
See the [GraphQL API Reference](reference/index.md) for up-to-date information.
Root-level queries are defined in
...
...
@@ -159,41 +162,33 @@ library GitLab uses on the backend.
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 connections
may have different max page size limits that are higher or lower.
Max page size | 100 records (nodes) per page. Applies to most connections in the API. Particular connections may have different max page size limits that are higher or lower.
[Max query complexity](#max-query-complexity) | `200` for unauthenticated requests and `250` for authenticated requests.
Request timeout | 30 seconds.
### Max query complexity
The GitLab GraphQL API scores the _complexity_ of a query. Generally, larger
queries will have a higher complexity score. This limit is designed to protect
queries have a higher complexity score. This limit is designed to protect
the API from performing queries that could negatively impact its overall performance.
The complexity of a single query is limited to a maximum of:
You can [query](getting_started.md#query-complexity) the complexity score of a query
and the limit for the request.
-`200` for unauthenticated requests.
-`250` for authenticated requests.
If a query exceeds the complexity limit, an error message response is
returned.
The complexity score of a query and limit for the request [can be queried for](getting_started.md#query-complexity).
If a query exceeds the complexity limit an error message response will
be returned.
In general, each field in a query will add `1` to the complexity score, although
this can be higher or lower for particular fields. Sometimes the addition of
In general, each field in a query adds `1` to the complexity score, although
this can be higher or lower for particular fields. Sometimes, adding
certain arguments may also increase the complexity of a query.
NOTE:
The complexity limits may be revised in future, and additionally, the complexity
of a query may be altered.
### Request timeout
Requests time out at 30 seconds.
### Spam
## Spam
GraphQL mutations can be detected as spam. If this happens, a
[GraphQL top-level error](https://spec.graphql.org/June2018/#sec-Errors) is raised. For example:
...
...
@@ -218,11 +213,11 @@ GraphQL mutations can be detected as spam. If this happens, a
}
```
If mutation is detected as potential spam and a CAPTCHA service is configured:
If a 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.
-Use the `captchaSiteKey` to obtain a CAPTCHA response value using the appropriate CAPTCHA API.
Only [Google reCAPTCHA v2](https://developers.google.com/recaptcha/docs/display) is supported.
-The request can be resubmitted with the `X-GitLab-Captcha-Response` and `X-GitLab-Spam-Log-Id` headers set.
-Resubmit the request with the `X-GitLab-Captcha-Response` and `X-GitLab-Spam-Log-Id` headers set.
