From ada52f947b142bd6fc8237154e4a1063f260f951 Mon Sep 17 00:00:00 2001
From: Evan Read <eread@gitlab.com>
Date: Tue, 12 Dec 2023 02:31:45 +0000
Subject: [PATCH] Refactor GraphQL index page
---
doc/api/graphql/getting_started.md | 2 +-
doc/api/graphql/index.md | 124 ++++++------------
doc/api/graphql/reference/index.md | 2 +-
doc/ci/resource_groups/index.md | 2 +-
doc/ci/testing/code_quality.md | 2 +-
doc/development/api_graphql_styleguide.md | 22 +++-
doc/development/fe_guide/index.md | 2 +-
.../fe_guide/migrating_from_vuex.md | 2 +-
doc/security/user_file_uploads.md | 2 +-
.../graphql/docs/templates/default.md.haml | 2 +-
10 files changed, 66 insertions(+), 96 deletions(-)
diff --git a/doc/api/graphql/getting_started.md b/doc/api/graphql/getting_started.md
index 3c938d0a4fd32..cf756027e01b6 100644
--- a/doc/api/graphql/getting_started.md
+++ b/doc/api/graphql/getting_started.md
@@ -343,7 +343,7 @@ More about introspection:
### Query complexity
-The calculated [complexity score and limit](index.md#max-query-complexity) for a query can be revealed to clients by
+The calculated [complexity score and limit](index.md#maximum-query-complexity) for a query can be revealed to clients by
querying for `queryComplexity`.
```graphql
diff --git a/doc/api/graphql/index.md b/doc/api/graphql/index.md
index 5ac647083851a..37bd9fc38ed94 100644
--- a/doc/api/graphql/index.md
+++ b/doc/api/graphql/index.md
@@ -6,8 +6,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w
# GraphQL API **(FREE ALL)**
-> Enabled and [made 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.
-
[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.
@@ -15,38 +13,22 @@ 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.
-There are no fixed endpoints and no data model, so you can add
-to the API without creating [breaking changes](../../development/deprecation_guidelines/index.md).
-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.
+The GraphQL API is [versionless](https://graphql.org/learn/best-practices/#versioning).
-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
+## Getting started
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
+### Interactive GraphQL explorer
+
+Explore the GraphQL API using the interactive GraphQL explorer, either:
-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`.
+- [On GitLab.com](https://gitlab.com/-/graphql-explorer).
+- On your self-managed GitLab instance on `https://<your-gitlab-site.com>/-/graphql-explorer`.
For more information, see [GraphiQL](getting_started.md#graphiql).
@@ -72,33 +54,44 @@ Global IDs are a convention used for caching and fetching in some client-side li
GitLab Global IDs are subject to change. If changed, the use of the old Global ID as an argument is deprecated and supported according to the [deprecation and breaking change](#breaking-changes) process.
You should not expect that a cached Global ID will be valid beyond the time of a GitLab GraphQL deprecation cycle.
+## Available top-level queries
+
+The top-level entry points for all queries are defined in the [`Query` type](reference/index.md#query-type) in the
+GraphQL reference.
+
+### Multiplex queries
+
+GitLab supports batching queries into a single request. For more information, see
+[Multiplex](https://graphql-ruby.org/queries/multiplex.html).
+
## Breaking changes
-The GitLab GraphQL API is [versionless](https://graphql.org/learn/best-practices/#versioning) and changes to the API are primarily backward-compatible.
+The GitLab GraphQL API is [versionless](https://graphql.org/learn/best-practices/#versioning) and changes to the API are
+primarily backward-compatible.
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).
-To avoid having a breaking change affect your integrations, you should
-familiarize yourself with the [deprecation and removal process](#deprecation-and-removal-process) and
-frequently [verify your API calls against the future breaking-change schema](#verify-against-the-future-breaking-change-schema).
+To avoid having a breaking change affect your integrations, you should:
+
+- Familiarize yourself with the [deprecation and removal process](#deprecation-and-removal-process).
+- Frequently [verify your API calls against the future breaking-change schema](#verify-against-the-future-breaking-change-schema).
For more information, see [Deprecating GitLab features](../../development/deprecation_guidelines/index.md).
### Breaking change exemptions
-Schema items
-[marked as alpha](../../development/api_graphql_styleguide.md#mark-schema-items-as-alpha)
-are exempt from the deprecation process, and can be removed or changed at any
+Schema items labeled as Experiments in the [GraphQL API reference](reference/index.md)
+are exempt from the deprecation process. These items can be removed or changed at any
time without notice.
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.
+deprecation and removal process. These fields can be removed at any time without notice.
WARNING:
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
+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.
@@ -111,8 +104,8 @@ This way, you can verify API calls ahead of a [breaking-change release](#depreca
before the items are actually removed from the schema.
To make these calls, add a
-`remove_deprecated=true` query parameter to the GitLab GraphQL API endpoint (for example,
-`https://gitlab.com/api/graphql?remove_deprecated=true` for GitLab SaaS GraphQL).
+`remove_deprecated=true` query parameter to the GraphQL API endpoint. For example,
+`https://gitlab.com/api/graphql?remove_deprecated=true` for GraphQL on GitLab.com.
### Deprecation and removal process
@@ -134,10 +127,8 @@ Items are marked as deprecated in:
The deprecation message provides an alternative for the deprecated schema item,
if applicable.
-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.
-You should [verify your API calls against the schema without the deprecated schema items](#verify-against-the-future-breaking-change-schema).
+To avoid experiencing breaking changes, you should remove the deprecated schema from your GraphQL API calls as soon as
+possible. You should [verify your API calls against the schema without the deprecated schema items](#verify-against-the-future-breaking-change-schema).
#### Deprecation example
@@ -145,7 +136,7 @@ The following fields are deprecated in different minor releases, but both
removed in GitLab 14.0:
| 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. |
@@ -153,50 +144,21 @@ removed in GitLab 14.0:
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:
-
-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 authenticated user.
-`users` | Information about a collection of users.
-`metaData` | Metadata about GitLab and the GraphQL API.
-`snippets` | Snippets visible to the authenticated 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
-[`app/graphql/types/query_type.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/graphql/types/query_type.rb).
-
-### Multiplex queries
-
-GitLab supports batching queries into a single request using
-[`@apollo/client/link/batch-http`](https://www.apollographql.com/docs/react/api/link/apollo-link-batch-http/). More
-information about multiplexed queries is also available for
-[GraphQL Ruby](https://graphql-ruby.org/queries/multiplex.html), the
-library GitLab uses on the backend.
-
## Limits
The following limits apply to the GitLab GraphQL API.
-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 size | 10,000 characters per query or mutation. If this limit is reached, use [variables](https://graphql.org/learn/queries/#variables) and [fragments](https://graphql.org/learn/queries/#fragments) to reduce the query or mutation size. Remove white spaces as last resort.
+| Limit | Default |
+|:------------------------------------------------------|:--------|
+| Maximum 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. |
+| [Maximum query complexity](#maximum-query-complexity) | 200 for unauthenticated requests and 250 for authenticated requests. |
+| Request timeout | 30 seconds. |
+| Maximum query size | 10,000 characters per query or mutation. If this limit is reached, use [variables](https://graphql.org/learn/queries/#variables) and [fragments](https://graphql.org/learn/queries/#fragments) to reduce the query or mutation size. Remove white spaces as last resort. |
-### Max query complexity
+### Maximum query complexity
The GitLab GraphQL API scores the _complexity_ of a query. Generally, larger
-queries have a higher complexity score. This limit is designed to protect
+queries have a higher complexity score. This limit is designed to protecting
the API from performing queries that could negatively impact its overall performance.
You can [query](getting_started.md#query-complexity) the complexity score of a query
@@ -209,14 +171,8 @@ 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.
-
## Resolve mutations detected as spam
-> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/327360) in GitLab 13.11.
-
GraphQL mutations can be detected as spam. If a mutation is detected as spam and:
- A CAPTCHA service is not configured, a
diff --git a/doc/api/graphql/reference/index.md b/doc/api/graphql/reference/index.md
index 6b281e1ade8a0..e15705de7d467 100644
--- a/doc/api/graphql/reference/index.md
+++ b/doc/api/graphql/reference/index.md
@@ -14,7 +14,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w
This documentation is self-generated based on GitLab current GraphQL schema.
-The API can be explored interactively using the [GraphiQL IDE](../index.md#graphiql).
+The API can be explored using the [interactive GraphQL explorer](../index.md#interactive-graphql-explorer).
Each table below documents a GraphQL type. Types match loosely to models, but not all
fields and methods on a model are available via GraphQL.
diff --git a/doc/ci/resource_groups/index.md b/doc/ci/resource_groups/index.md
index 9c0f7f229cdb9..aca272dddee1c 100644
--- a/doc/ci/resource_groups/index.md
+++ b/doc/ci/resource_groups/index.md
@@ -277,7 +277,7 @@ To get job information from the GraphQL API:
1. Go to the pipeline details page.
1. Select the **Jobs** tab and find the ID of the stuck job.
-1. Go to [GraphiQL explorer](../../api/graphql/index.md#graphiql).
+1. Go to the [interactive GraphQL explorer](../../api/graphql/index.md#interactive-graphql-explorer).
1. Run the following query:
```graphql
diff --git a/doc/ci/testing/code_quality.md b/doc/ci/testing/code_quality.md
index 795431a61a25f..4155666ca240f 100644
--- a/doc/ci/testing/code_quality.md
+++ b/doc/ci/testing/code_quality.md
@@ -720,7 +720,7 @@ To gain insight into the errors, you can execute a GraphQL query using the follo
1. Go to the pipeline details page.
1. Append `.json` to the URL.
1. Copy the `iid` of the pipeline.
-1. Go to [GraphiQL explorer](../../api/graphql/index.md#graphiql).
+1. Go to the [interactive GraphQL explorer](../../api/graphql/index.md#interactive-graphql-explorer).
1. Run the following query:
```graphql
diff --git a/doc/development/api_graphql_styleguide.md b/doc/development/api_graphql_styleguide.md
index 4cee0ac57dfa5..f6d39ff954b8d 100644
--- a/doc/development/api_graphql_styleguide.md
+++ b/doc/development/api_graphql_styleguide.md
@@ -8,6 +8,20 @@ info: Any user with at least the Maintainer role can merge updates to this conte
This document outlines the style guide for the GitLab [GraphQL API](../api/graphql/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.
+
+To help us meet this vision, the frontend should use GraphQL in preference to
+the REST API for new features.
+The GraphQL API is [versionless](https://graphql.org/learn/best-practices/#versioning).
+
+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.
+
## How GitLab implements GraphQL
<!-- vale gitlab.Spelling = NO -->
@@ -78,7 +92,7 @@ a connection.
### Max complexity
-Complexity is explained [on our client-facing API page](../api/graphql/index.md#max-query-complexity).
+Complexity is explained [on our client-facing API page](../api/graphql/index.md#maximum-query-complexity).
Fields default to adding `1` to a query's complexity score, but developers can
[specify a custom complexity](#field-complexity) when defining a field.
@@ -477,7 +491,7 @@ field :tags,
### Field complexity
The GitLab GraphQL API uses a _complexity_ score to limit performing overly complex queries.
-Complexity is described in [our client documentation](../api/graphql/index.md#max-query-complexity) on the topic.
+Complexity is described in [our client documentation](../api/graphql/index.md#maximum-query-complexity) on the topic.
Complexity limits are defined in [`app/graphql/gitlab_schema.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/graphql/gitlab_schema.rb).
@@ -864,8 +878,8 @@ mount_mutation Mutations::Ci::JobArtifact::BulkDestroy, alpha: { milestone: '15.
Alpha GraphQL items is a custom GitLab feature that leverages GraphQL deprecations. An Alpha item
appears as deprecated in the GraphQL schema. Like all deprecated schema items, you can test an
-Alpha field in [GraphiQL](../api/graphql/index.md#graphiql). However, be aware that the GraphiQL
-autocomplete editor doesn't suggest deprecated fields.
+Alpha field in the [interactive GraphQL explorer](../api/graphql/index.md#interactive-graphql-explorer) (GraphiQL).
+However, be aware that the GraphiQL autocomplete editor doesn't suggest deprecated fields.
The item shows as Alpha in our generated GraphQL documentation and its GraphQL schema description.
diff --git a/doc/development/fe_guide/index.md b/doc/development/fe_guide/index.md
index fc42e02dfeb6b..3c7c000dbe6c1 100644
--- a/doc/development/fe_guide/index.md
+++ b/doc/development/fe_guide/index.md
@@ -24,7 +24,7 @@ When it comes to CSS, we use a utils-based CSS approach. GitLab has its own CSS
We also use [SCSS](https://sass-lang.com) and plain JavaScript with
modern ECMAScript standards supported through [Babel](https://babeljs.io/) and ES module support through [webpack](https://webpack.js.org/).
-When making API calls, we use [GraphQL](graphql.md) as [the first choice](../../api/graphql/index.md#vision). There are still instances where GitLab REST API is used such as when creating new simple HAML pages or in legacy part of the codebase, but we should always default to GraphQL when possible.
+When making API calls, we use [GraphQL](graphql.md) as [the first choice](../api_graphql_styleguide.md#vision). There are still instances where GitLab REST API is used such as when creating new simple HAML pages or in legacy part of the codebase, but we should always default to GraphQL when possible.
We use [Apollo](https://www.apollographql.com/) as our global state manager and [GraphQL client](graphql.md).
[VueX](vuex.md) is still in use across the codebase, but it is no longer the recommended global state manager.
diff --git a/doc/development/fe_guide/migrating_from_vuex.md b/doc/development/fe_guide/migrating_from_vuex.md
index 347902feafa31..45a1ea0b7ee2b 100644
--- a/doc/development/fe_guide/migrating_from_vuex.md
+++ b/doc/development/fe_guide/migrating_from_vuex.md
@@ -8,7 +8,7 @@ info: Any user with at least the Maintainer role can merge updates to this conte
## Why?
-We have defined [GraphQL as our primary API](../../api/graphql/index.md#vision) for all user-facing features,
+We have defined the [GraphQL API](../../api/graphql/index.md) as [the primary API](../api_graphql_styleguide.md#vision) for all user-facing features,
so we can safely assume that whenever GraphQL is present, so will the Apollo Client.
We [do not want to use Vuex with Apollo](graphql.md#using-with-vuex), so the VueX stores count
will naturally decline over time as we move from the REST API to GraphQL.
diff --git a/doc/security/user_file_uploads.md b/doc/security/user_file_uploads.md
index fe8fb11fe65b1..e73bdf4ced23f 100644
--- a/doc/security/user_file_uploads.md
+++ b/doc/security/user_file_uploads.md
@@ -60,7 +60,7 @@ You cannot select this option for public projects.
You should delete an uploaded file when that file contains sensitive or confidential information. When you have deleted that file, users cannot access the file and the direct URL returns a 404 error.
-Project Owners and Maintainers can use the [interactive GraphiQL explorer](../api/graphql/index.md#graphiql) to access a [GraphQL endpoint](../api/graphql/reference/index.md#mutationuploaddelete) and delete an uploaded file.
+Project Owners and Maintainers can use the [interactive GraphQL explorer](../api/graphql/index.md#interactive-graphql-explorer) to access a [GraphQL endpoint](../api/graphql/reference/index.md#mutationuploaddelete) and delete an uploaded file.
For example:
diff --git a/tooling/graphql/docs/templates/default.md.haml b/tooling/graphql/docs/templates/default.md.haml
index 57c3ca7a47666..1502afde181df 100644
--- a/tooling/graphql/docs/templates/default.md.haml
+++ b/tooling/graphql/docs/templates/default.md.haml
@@ -7,7 +7,7 @@
This documentation is self-generated based on GitLab current GraphQL schema.
- The API can be explored interactively using the [GraphiQL IDE](../index.md#graphiql).
+ The API can be explored using the [interactive GraphQL explorer](../index.md#interactive-graphql-explorer).
Each table below documents a GraphQL type. Types match loosely to models, but not all
fields and methods on a model are available via GraphQL.
--
GitLab