diff options
Diffstat (limited to 'doc/api/graphql/index.md')
| -rw-r--r-- | doc/api/graphql/index.md | 28 |
1 files changed, 27 insertions, 1 deletions
diff --git a/doc/api/graphql/index.md b/doc/api/graphql/index.md index ec48bf4940b..88e657a5d2f 100644 --- a/doc/api/graphql/index.md +++ b/doc/api/graphql/index.md @@ -16,6 +16,20 @@ added to the API without creating breaking changes. This allows us to have a versionless API as described in [the GraphQL documentation](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, although the alpha status of GraphQL may prevent +this from being a possibility at times. + +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. + ## Enabling the GraphQL feature The GraphQL API itself is currently in Alpha, and therefore hidden behind a @@ -29,7 +43,19 @@ curl --data "value=100" --header "PRIVATE-TOKEN: <your_access_token>" https://gi ## Available queries -A first iteration of a GraphQL API includes a query for: `project`. Within a project it is also possible to fetch a `mergeRequest` by IID. +A first iteration of a GraphQL API includes the following queries + +1. `project` : Within a project it is also possible to fetch a `mergeRequest` by IID. +1. `group` : Only basic group information is currently supported. +1. `namespace` : Within a namespace it is also possible to fetch `projects`. + +### Multiplex queries + +GitLab supports batching queries into a single request using +[apollo-link-batch-http](https://www.apollographql.com/docs/link/links/batch-http). More +info about multiplexed queries is also available for +[graphql-ruby](https://graphql-ruby.org/queries/multiplex.html) the +library GitLab uses on the backend. ## GraphiQL |