diff options
Diffstat (limited to 'doc/api/graphql/index.md')
| -rw-r--r-- | doc/api/graphql/index.md | 223 |
1 files changed, 107 insertions, 116 deletions
diff --git a/doc/api/graphql/index.md b/doc/api/graphql/index.md index 3523276bdf5..bcaa5930faf 100644 --- a/doc/api/graphql/index.md +++ b/doc/api/graphql/index.md @@ -6,27 +6,42 @@ info: To determine the technical writer assigned to the Stage/Group associated w # GraphQL API **(FREE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/19008) in GitLab 11.0 (enabled by feature flag `graphql`). -> - [Always enabled](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/30444) in GitLab 12.1. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/19008) in GitLab 11.0 [with a flag](../../administration/feature_flags.md) named `graphql`. +> - [Enabled](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/30444) in GitLab 12.1. -## Getting Started +[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. -For those new to the GitLab GraphQL API, see -[Getting started with GitLab GraphQL API](getting_started.md). +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. -### Quick Reference +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). -- The GitLab GraphQL API endpoint is located at `/api/graphql`. -- Get an [introduction to GraphQL from graphql.org](https://graphql.org/). -- GitLab supports a wide range of resources, listed in the [GraphQL API Reference](reference/index.md). +## 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. -### Examples +To help us meet this vision, the frontend should use GraphQL in preference to +the REST API for new features. -To work with sample queries that pull data from public projects on GitLab.com, -see the menu options in the left-hand -documentation menu, under API > GraphQL at `https://docs.gitlab.com/ee/api/graphql/`. +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. -The [Getting started](getting_started.md) page includes different methods to customize GraphQL queries. +## 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`. ### GraphiQL @@ -34,104 +49,102 @@ Explore the GraphQL API using the interactive [GraphiQL explorer](https://gitlab or on your self-managed GitLab instance on `https://<your-gitlab-site.com>/-/graphql-explorer`. -See the [GitLab GraphQL overview](getting_started.md#graphiql) for more information about the GraphiQL Explorer. +For more information, see [GraphiQL](getting_started.md#graphiql). -## What is GraphQL? +### View GraphQL examples -[GraphQL](https://graphql.org/) is a query language for APIs that -allows clients to request exactly the data they need, making it -possible to get all required data in a limited number of requests. +You can work with sample queries that pull data from public projects on GitLab.com: -The GraphQL data (fields) can be described in the form of types, -allowing clients to use [client-side GraphQL -libraries](https://graphql.org/code/#graphql-clients) to consume the -API and avoid manual parsing. +- [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) -Since there's no fixed endpoints and data model, new abilities can be -added to the API without creating [breaking changes](../../development/contributing/#breaking-changes). This allows us to -have a versionless API as described in [the GraphQL -documentation](https://graphql.org/learn/best-practices/#versioning). +The [get started](getting_started.md) page includes different methods to customize GraphQL queries. -## Vision +### Update the GraphQL API reference -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. +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). -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. +Run the commands using the [GitLab Development Kit](https://gitlab.com/gitlab-org/gitlab-development-kit/). ## 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 +[deprecation process](https://about.gitlab.com/handbook/product/gitlab-the-product/#breaking-changes-deprecations-and-removing-features). -Parts of the schema marked for removal from the GitLab GraphQL API are first **deprecated** but still available -for at least six releases, and then **removed entirely**. -Removals occur at `X.0` and `X.6` releases. +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. -The process is as follows: +Items are marked as deprecated in: -1. The item is marked as deprecated in the schema. It will be displayed as deprecated in the - [GraphQL API Reference](reference/index.md) and in introspection queries. -1. Removals are announced at least one release prior in the [Deprecations](https://about.gitlab.com/handbook/marketing/blog/release-posts/#deprecations) - section of the release post (at or prior to `X.11` and `X.5` releases). -1. Items meeting criteria are removed in `X.0` or `X.6` and added to: +- 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. - - The [Removals](https://about.gitlab.com/handbook/marketing/blog/release-posts/#removals) section of the Release Post. - - The [Removed items page](removed_items.md). +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. -This gives consumers of the GraphQL API a minimum of six months to update their GraphQL queries. +The deprecation message provides an alternative for the deprecated schema item, +if applicable. -When an item is deprecated or removed, an alternative is provided if available. +#### Deprecation example -**Example:** +The following fields are deprecated in different minor releases, but both +removed in GitLab 14.0: -A field marked as deprecated in `12.7` can be used until its removal in `13.6`. +| 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. | ### List of removed items -View the [fields, enums, and other items we removed](removed_items.md) from the GraphQL API. +View the [list of items removed](removed_items.md) in previous releases. ## Available queries 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 @@ -149,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. +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. ### 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: - -- `200` for unauthenticated requests. -- `250` for authenticated requests. +You can [query](getting_started.md#query-complexity) the complexity score of a query +and the limit for the request. -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 is +returned. -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: @@ -208,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. ```json { @@ -235,17 +240,3 @@ If mutation is detected as potential spam and a CAPTCHA service is configured: } } ``` - -## Reference - -The GitLab GraphQL reference [is available](reference/index.md). - -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 the -[Rake tasks for developers](../../development/rake_tasks.md#update-graphql-documentation-and-schema-definitions) page. - -Be sure to run these commands using the [GitLab Development Kit](https://gitlab.com/gitlab-org/gitlab-development-kit/). |