debian-mirror-gitlab/doc/api/graphql/index.md

242 lines
9.7 KiB
Markdown
Raw Normal View History

2021-01-29 00:20:46 +05:30
---
2021-10-27 15:23:28 +05:30
stage: Ecosystem
group: Integrations
2021-02-22 17:27:13 +05:30
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
2021-01-29 00:20:46 +05:30
---
2021-11-11 11:23:49 +05:30
# GraphQL API **(FREE)**
2018-11-08 19:23:39 +05:30
2022-03-02 08:16:31 +05:30
> [Generally available](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/30444) in GitLab 12.1. [Feature flag `graphql`](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/30444) removed.
2018-11-08 19:23:39 +05:30
2022-01-26 12:08:38 +05:30
[GraphQL](https://graphql.org/) is a query language for APIs. You can use it to
request the exact data you need, and therefore limit the number of requests you need.
2020-01-01 13:55:28 +05:30
2022-01-26 12:08:38 +05:30
GraphQL data is arranged in types, so your client can use
[client-side GraphQL libraries](https://graphql.org/code/#graphql-clients)
to consume the API and avoid manual parsing.
2020-01-01 13:55:28 +05:30
2022-01-26 12:08:38 +05:30
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).
2020-01-01 13:55:28 +05:30
2022-01-26 12:08:38 +05:30
## 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.
2020-01-01 13:55:28 +05:30
2022-01-26 12:08:38 +05:30
To help us meet this vision, the frontend should use GraphQL in preference to
the REST API for new features.
2020-10-24 23:57:45 +05:30
2022-01-26 12:08:38 +05:30
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.
2020-10-24 23:57:45 +05:30
2022-01-26 12:08:38 +05:30
## Work with GraphQL
If you're new to the GitLab GraphQL API, see [Get started with GitLab GraphQL API](getting_started.md).
You can view the available resources in the [GraphQL API reference](reference/index.md).
The reference is automatically generated from the GitLab GraphQL schema and
written to a Markdown file.
The GitLab GraphQL API endpoint is located at `/api/graphql`.
2020-10-24 23:57:45 +05:30
### GraphiQL
2020-01-01 13:55:28 +05:30
Explore the GraphQL API using the interactive [GraphiQL explorer](https://gitlab.com/-/graphql-explorer),
or on your self-managed GitLab instance on
`https://<your-gitlab-site.com>/-/graphql-explorer`.
2022-01-26 12:08:38 +05:30
For more information, see [GraphiQL](getting_started.md#graphiql).
2020-01-01 13:55:28 +05:30
2022-01-26 12:08:38 +05:30
### View GraphQL examples
2020-01-01 13:55:28 +05:30
2022-01-26 12:08:38 +05:30
You can work with sample queries that pull data from public projects on GitLab.com:
2018-11-08 19:23:39 +05:30
2022-01-26 12:08:38 +05:30
- [Create an audit report](audit_report.md)
- [Identify issue boards](sample_issue_boards.md)
- [Query users](users_example.md)
- [Use custom emojis](custom_emoji.md)
2018-11-08 19:23:39 +05:30
2022-01-26 12:08:38 +05:30
The [get started](getting_started.md) page includes different methods to customize GraphQL queries.
2018-11-08 19:23:39 +05:30
2022-01-26 12:08:38 +05:30
### Update the GraphQL API reference
2019-09-04 21:01:54 +05:30
2022-01-26 12:08:38 +05:30
If you change the GraphQL schema, create a merge request to get your changes approved.
To generate the required documentation and schema, see
[Rake tasks for developers](../../development/rake_tasks.md#update-graphql-documentation-and-schema-definitions).
2019-09-04 21:01:54 +05:30
2022-01-26 12:08:38 +05:30
Run the commands using the [GitLab Development Kit](https://gitlab.com/gitlab-org/gitlab-development-kit/).
2019-09-04 21:01:54 +05:30
2021-04-17 20:07:23 +05:30
## Breaking changes
2020-11-24 15:15:51 +05:30
2022-01-26 12:08:38 +05:30
The GitLab GraphQL API is [versionless](https://graphql.org/learn/best-practices/#versioning) and changes to the API are primarily backward-compatible.
2020-11-24 15:15:51 +05:30
2022-01-26 12:08:38 +05:30
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).
2020-11-24 15:15:51 +05:30
2022-01-26 12:08:38 +05:30
Learn more about [breaking changes](../../development/contributing/#breaking-changes).
2020-11-24 15:15:51 +05:30
2022-01-26 12:08:38 +05:30
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.
2021-09-30 23:02:18 +05:30
2022-01-26 12:08:38 +05:30
To avoid having a breaking change affect your integrations, you should
familiarize yourself with the deprecation and removal process.
2020-11-24 15:15:51 +05:30
2021-09-04 01:27:46 +05:30
WARNING:
2022-01-26 12:08:38 +05:30
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.
2021-09-04 01:27:46 +05:30
2022-01-26 12:08:38 +05:30
### Deprecation and removal process
2021-03-08 18:12:59 +05:30
2022-01-26 12:08:38 +05:30
The deprecation and removal process for the GitLab GraphQL API aligns with the wider GitLab
[deprecation process](https://about.gitlab.com/handbook/product/gitlab-the-product/#breaking-changes-deprecations-and-removing-features).
2021-04-17 20:07:23 +05:30
2022-01-26 12:08:38 +05:30
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. They are then [removed](https://about.gitlab.com/handbook/product/gitlab-the-product/#removal)
entirely during the next `XX.0` major release.
2021-04-17 20:07:23 +05:30
2022-01-26 12:08:38 +05:30
Items are marked as deprecated in:
2021-04-17 20:07:23 +05:30
2022-01-26 12:08:38 +05:30
- 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 from release posts.
- Introspection queries of the GraphQL API.
2021-04-17 20:07:23 +05:30
2022-01-26 12:08:38 +05:30
NOTE:
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.
2021-04-17 20:07:23 +05:30
2022-01-26 12:08:38 +05:30
The deprecation message provides an alternative for the deprecated schema item,
if applicable.
2021-04-17 20:07:23 +05:30
2022-01-26 12:08:38 +05:30
#### Deprecation example
2021-04-17 20:07:23 +05:30
2022-01-26 12:08:38 +05:30
The following fields are deprecated in different minor releases, but both
removed in GitLab 14.0:
2021-04-17 20:07:23 +05:30
2022-01-26 12:08:38 +05:30
| Field deprecated in | Reason |
| ------------------- | --- |
| 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. |
2021-04-17 20:07:23 +05:30
2021-01-29 00:20:46 +05:30
### List of removed items
2022-01-26 12:08:38 +05:30
View the [list of items removed](removed_items.md) in previous releases.
2021-01-29 00:20:46 +05:30
2018-11-08 19:23:39 +05:30
## Available queries
2020-01-01 13:55:28 +05:30
The GraphQL API includes the following queries at the root level:
2019-07-31 22:56:46 +05:30
2022-01-26 12:08:38 +05:30
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.
2020-03-13 15:44:24 +05:30
See the [GraphQL API Reference](reference/index.md) for up-to-date information.
2020-01-01 13:55:28 +05:30
Root-level queries are defined in
2021-09-04 01:27:46 +05:30
[`app/graphql/types/query_type.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/graphql/types/query_type.rb).
2019-09-04 21:01:54 +05:30
### Multiplex queries
2019-07-31 22:56:46 +05:30
2019-09-04 21:01:54 +05:30
GitLab supports batching queries into a single request using
2022-04-04 11:22:00 +05:30
[`@apollo/client/link/batch-http`](https://www.apollographql.com/docs/react/api/link/apollo-link-batch-http/). More
2020-04-22 19:07:51 +05:30
information about multiplexed queries is also available for
[GraphQL Ruby](https://graphql-ruby.org/queries/multiplex.html), the
2019-09-04 21:01:54 +05:30
library GitLab uses on the backend.
2018-11-08 19:23:39 +05:30
2021-03-11 19:13:27 +05:30
## Limits
The following limits apply to the GitLab GraphQL API.
2022-01-26 12:08:38 +05:30
Limit | Default
---------------------|---------------------------------------------------------------------
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.
2021-03-11 19:13:27 +05:30
### Max query complexity
The GitLab GraphQL API scores the _complexity_ of a query. Generally, larger
2022-01-26 12:08:38 +05:30
queries have a higher complexity score. This limit is designed to protect
2021-03-11 19:13:27 +05:30
the API from performing queries that could negatively impact its overall performance.
2022-01-26 12:08:38 +05:30
You can [query](getting_started.md#query-complexity) the complexity score of a query
and the limit for the request.
2021-03-11 19:13:27 +05:30
2022-01-26 12:08:38 +05:30
If a query exceeds the complexity limit, an error message response is
returned.
2021-03-11 19:13:27 +05:30
2022-01-26 12:08:38 +05:30
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
2021-03-11 19:13:27 +05:30
certain arguments may also increase the complexity of a query.
2021-04-17 20:07:23 +05:30
NOTE:
2021-03-11 19:13:27 +05:30
The complexity limits may be revised in future, and additionally, the complexity
of a query may be altered.
2022-01-26 12:08:38 +05:30
## Spam
2021-04-29 21:17:54 +05:30
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:
```json
{
"errors": [
{
"message": "Request denied. Spam detected",
"locations": [ { "line": 6, "column": 7 } ],
"path": [ "updateSnippet" ],
"extensions": {
"spam": true
}
}
],
"data": {
"updateSnippet": {
"snippet": null
}
}
}
```
2022-01-26 12:08:38 +05:30
If a mutation is detected as potential spam and a CAPTCHA service is configured:
2021-04-29 21:17:54 +05:30
2022-01-26 12:08:38 +05:30
- Use the `captchaSiteKey` to obtain a CAPTCHA response value using the appropriate CAPTCHA API.
2021-04-29 21:17:54 +05:30
Only [Google reCAPTCHA v2](https://developers.google.com/recaptcha/docs/display) is supported.
2022-01-26 12:08:38 +05:30
- Resubmit the request with the `X-GitLab-Captcha-Response` and `X-GitLab-Spam-Log-Id` headers set.
2021-04-29 21:17:54 +05:30
```json
{
"errors": [
{
"message": "Request denied. Solve CAPTCHA challenge and retry",
"locations": [ { "line": 6, "column": 7 } ],
"path": [ "updateSnippet" ],
"extensions": {
"needsCaptchaResponse": true,
"captchaSiteKey": "6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI",
"spamLogId": 67
}
}
],
"data": {
"updateSnippet": {
"snippet": null,
}
}
}
```