diff --git a/doc/api/graphql/getting_started.md b/doc/api/graphql/getting_started.md index 2df434cdb06dfd4dbbc7c595cbdc1bfce6d4d6a6..3c938d0a4fd32ceb6d170361e8f2cbca5e898665 100644 --- a/doc/api/graphql/getting_started.md +++ b/doc/api/graphql/getting_started.md @@ -97,6 +97,7 @@ NOTE: In the GitLab GraphQL API, `id` refers to a [Global ID](https://graphql.org/learn/global-object-identification/), which is an object identifier in the format of `"gid://gitlab/Issue/123"`. +For more information, see [Global IDs](index.md#global-ids). [GitLab GraphQL Schema](reference/index.md) outlines which objects and fields are available for clients to query and their corresponding data types. diff --git a/doc/api/graphql/index.md b/doc/api/graphql/index.md index 39484e83811c9e5ed2b87f7b81df8d4b3aff44d2..5ac647083851af9493a8f3e9c6ce01267ccc8db1 100644 --- a/doc/api/graphql/index.md +++ b/doc/api/graphql/index.md @@ -61,6 +61,17 @@ You can work with sample queries that pull data from public projects on GitLab.c The [get started](getting_started.md) page includes different methods to customize GraphQL queries. +### Global IDs + +In the GitLab GraphQL API, an `id` field is nearly always a [Global ID](https://graphql.org/learn/global-object-identification/) +and never a database primary key ID. A Global ID in the GitLab GraphQL API +begins with `"gid://gitlab/"`. For example, `"gid://gitlab/Issue/123"`. + +Global IDs are a convention used for caching and fetching in some client-side libraries. + +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. + ## Breaking changes The GitLab GraphQL API is [versionless](https://graphql.org/learn/best-practices/#versioning) and changes to the API are primarily backward-compatible. diff --git a/doc/development/api_graphql_styleguide.md b/doc/development/api_graphql_styleguide.md index e3162edca721001bdd97ffe53f445a61b0df5cad..4cee0ac57dfa5e6b351fb09e265686a3d8a938a6 100644 --- a/doc/development/api_graphql_styleguide.md +++ b/doc/development/api_graphql_styleguide.md @@ -190,6 +190,7 @@ See also: - [Exposing Global IDs](#exposing-global-ids). - [Mutation arguments](#object-identifier-arguments). - [Deprecating Global IDs](#deprecate-global-ids). +- [Customer-facing Global ID documentation](../api/graphql/index.md#global-ids). We have a custom scalar type (`Types::GlobalIDType`) which should be used as the type of input and output arguments when the value is a `GlobalID`. The benefits