2019-09-30 21:07:59 +05:30
|
|
|
# GraphQL API
|
2018-11-08 19:23:39 +05:30
|
|
|
|
2019-09-30 21:07:59 +05:30
|
|
|
> - [Introduced][ce-19008] in GitLab 11.0 (enabled by feature flag `graphql`).
|
2019-12-04 20:38:33 +05:30
|
|
|
> - [Always enabled](https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/30444)
|
2019-09-30 21:07:59 +05:30
|
|
|
in GitLab 12.1.
|
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,
|
|
|
|
|
allowing clients to use [clientside GraphQL
|
|
|
|
|
libraries](https://graphql.org/code/#graphql-clients) to consume the
|
|
|
|
|
API and avoid manual parsing.
|
|
|
|
|
|
|
|
|
|
Since there's no fixed endpoints and datamodel, new abilities can be
|
|
|
|
|
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
|
|
|
|
|
|
2019-07-31 22:56:46 +05:30
|
|
|
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.
|
2019-09-30 21:07:59 +05:30
|
|
|
1. `group` : Basic group information and epics **(ULTIMATE)** are currently supported.
|
2019-09-04 21:01:54 +05:30
|
|
|
1. `namespace` : Within a namespace it is also possible to fetch `projects`.
|
|
|
|
|
|
|
|
|
|
### 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
|
2019-09-04 21:01:54 +05:30
|
|
|
info about multiplexed queries is also available for
|
|
|
|
|
[graphql-ruby](https://graphql-ruby.org/queries/multiplex.html) the
|
|
|
|
|
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)
|
|
|
|
|
|
2018-11-08 19:23:39 +05:30
|
|
|
## GraphiQL
|
|
|
|
|
|
|
|
|
|
The API can be explored by using the GraphiQL IDE, it is available on your
|
|
|
|
|
instance on `gitlab.example.com/-/graphql-explorer`.
|
|
|
|
|
|
2019-12-04 20:38:33 +05:30
|
|
|
[ce-19008]: https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/19008
|
2018-11-08 19:23:39 +05:30
|
|
|
[features-api]: ../features.md
|
