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

99 lines
4 KiB
Markdown
Raw Normal View History

2019-09-30 21:07:59 +05:30
# GraphQL API
2018-11-08 19:23:39 +05:30
2020-04-22 19:07:51 +05:30
> - [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.
2018-11-08 19:23:39 +05:30
2020-01-01 13:55:28 +05:30
## Getting Started
For those new to the GitLab GraphQL API, see
[Getting started with GitLab GraphQL API](getting_started.md).
### Quick Reference
- GitLab's 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).
2020-10-24 23:57:45 +05:30
### Examples
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/`.
The [Getting started](getting_started.md) page includes different methods to customize GraphQL queries.
### 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`.
See the [GitLab GraphQL overview](getting_started.md#graphiql) for more information about the GraphiQL Explorer.
## What is GraphQL?
2018-11-08 19:23:39 +05:30
[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.
The GraphQL data (fields) can be described in the form of types,
2020-06-23 00:09:42 +05:30
allowing clients to use [client-side GraphQL
2018-11-08 19:23:39 +05:30
libraries](https://graphql.org/code/#graphql-clients) to consume the
API and avoid manual parsing.
2020-06-23 00:09:42 +05:30
Since there's no fixed endpoints and data model, new abilities can be
2018-11-08 19:23:39 +05:30
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).
2019-09-04 21:01:54 +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.
To help us meet this vision, the frontend should use GraphQL in preference to
2019-09-30 21:07:59 +05:30
the REST API for new features.
2019-09-04 21:01:54 +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.
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
2020-03-13 15:44:24 +05:30
1. `project` : Project information, with many of its associations such as issues and merge requests.
2019-09-30 21:07:59 +05:30
1. `group` : Basic group information and epics **(ULTIMATE)** are currently supported.
2020-06-23 00:09:42 +05:30
1. `user` : Information about a particular user.
2019-09-04 21:01:54 +05:30
1. `namespace` : Within a namespace it is also possible to fetch `projects`.
2020-01-01 13:55:28 +05:30
1. `currentUser`: Information about the currently logged in user.
2020-06-23 00:09:42 +05:30
1. `users`: Information about a collection of users.
2020-01-01 13:55:28 +05:30
1. `metaData`: Metadata about GitLab and the GraphQL API.
1. `snippets`: Snippets visible to the currently logged in user.
2020-03-13 15:44:24 +05:30
New associations and root level objects are constantly being added.
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
[`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
2019-12-21 20:55:43 +05:30
[apollo-link-batch-http](https://www.apollographql.com/docs/link/links/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
2019-09-30 21:07:59 +05:30
## Reference
GitLab's GraphQL reference [is available](reference/index.md).
It is automatically generated from GitLab's GraphQL schema and embedded in a Markdown file.
2019-12-26 22:10:19 +05:30
Machine-readable versions are also available:
- [JSON format](reference/gitlab_schema.json)
- [IDL format](reference/gitlab_schema.graphql)