2020-10-26 21:08:22 +00:00
---
2021-08-02 15:08:56 +00:00
stage: Ecosystem
group: Integrations
2020-11-26 06:09:20 +00:00
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
2020-10-26 21:08:22 +00:00
---
2021-06-09 15:10:05 +00:00
# Get started with GitLab GraphQL API **(FREE)**
2019-11-22 09:06:20 +00:00
2020-12-16 21:09:57 +00:00
This guide demonstrates basic usage of the GitLab GraphQL API.
2019-11-22 09:06:20 +00:00
2021-07-01 18:07:29 +00:00
Read the [GraphQL API style guide ](../../development/api_graphql_styleguide.md )
2021-06-09 15:10:05 +00:00
for implementation details aimed at developers who wish to work on developing
the API itself.
2019-11-22 09:06:20 +00:00
## Running examples
The examples documented here can be run using:
- The command line.
- GraphiQL.
### Command line
2021-06-09 15:10:05 +00:00
You can run GraphQL queries in a `curl` request on the command line on your
local computer. A GraphQL request can be made as a `POST` request to `/api/graphql`
with the query as the payload. You can authorize your request by generating a
[personal access token ](../../user/profile/personal_access_tokens.md ) to use as
a bearer token.
2019-11-22 09:06:20 +00:00
Example:
2020-01-30 15:09:15 +00:00
```shell
2019-11-27 09:06:29 +00:00
GRAPHQL_TOKEN=< your-token >
2021-06-02 15:09:59 +00:00
curl "https://gitlab.com/api/graphql" --header "Authorization: Bearer $GRAPHQL_TOKEN" \
--header "Content-Type: application/json" --request POST \
--data "{\"query\": \"query {currentUser {name}}\"}"
2019-11-22 09:06:20 +00:00
```
### GraphiQL
2021-06-09 15:10:05 +00:00
GraphiQL (pronounced "graphical") allows you to run queries directly against
the server endpoint with syntax highlighting and autocomplete. It also allows
you to explore the schema and types.
2019-11-22 09:06:20 +00:00
The examples below:
2021-06-09 15:10:05 +00:00
- Can be run directly against GitLab 11.0 or later, though some of the types
and fields may not be supported in older versions.
- Works against GitLab.com without any further setup. Make sure you are signed
in and navigate to the [GraphiQL Explorer ](https://gitlab.com/-/graphql-explorer ).
2019-11-22 09:06:20 +00:00
2021-06-09 15:10:05 +00:00
If you want to run the queries locally, or on a self-managed instance, you must
either:
2019-11-22 09:06:20 +00:00
2021-06-09 15:10:05 +00:00
- Create the `gitlab-org` group with a project called `graphql-sandbox` under
it. Create several issues in the project.
- Edit the queries to replace `gitlab-org/graphql-sandbox` with your own group
and project.
2019-11-22 09:06:20 +00:00
2021-06-09 15:10:05 +00:00
Refer to [running GraphiQL ](index.md#graphiql ) for more information.
2019-11-22 09:06:20 +00:00
2020-12-04 21:09:29 +00:00
NOTE:
2019-11-22 09:06:20 +00:00
If you are running GitLab 11.0 to 12.0, enable the `graphql`
[feature flag ](../features.md#set-or-create-a-feature ).
## Queries and mutations
The GitLab GraphQL API can be used to perform:
- Queries for data retrieval.
- [Mutations ](#mutations ) for creating, updating, and deleting data.
2020-12-04 21:09:29 +00:00
NOTE:
2020-08-11 00:10:18 +00:00
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"` .
2019-11-22 09:06:20 +00:00
2020-12-16 21:09:57 +00:00
[GitLab GraphQL Schema ](reference/index.md ) outlines which objects and fields are
2019-11-22 09:06:20 +00:00
available for clients to query and their corresponding data types.
2021-06-09 15:10:05 +00:00
Example: Get only the names of all the projects the currently logged in user can
access (up to a limit) in the group `gitlab-org` .
2019-11-22 09:06:20 +00:00
```graphql
query {
group(fullPath: "gitlab-org") {
id
name
projects {
nodes {
name
}
}
}
}
```
Example: Get a specific project and the title of Issue #2 .
```graphql
query {
2019-11-27 09:06:29 +00:00
project(fullPath: "gitlab-org/graphql-sandbox") {
name
issue(iid: "2") {
title
}
}
}
2019-11-22 09:06:20 +00:00
```
2019-11-27 09:06:29 +00:00
### Graph traversal
2019-11-22 09:06:20 +00:00
When retrieving child nodes use:
2021-06-09 15:10:05 +00:00
- The `edges { node { } }` syntax.
- The short form `nodes { }` syntax.
2019-11-22 09:06:20 +00:00
Underneath it all is a graph we are traversing, hence the name GraphQL.
2021-06-09 15:10:05 +00:00
Example: Get the name of a project, and the titles of all its issues.
2019-11-22 09:06:20 +00:00
```graphql
query {
project(fullPath: "gitlab-org/graphql-sandbox") {
name
issues {
nodes {
title
description
}
}
}
}
```
More about queries:
2021-06-09 15:10:05 +00:00
[GraphQL documentation ](https://graphql.org/learn/queries/ )
2019-11-22 09:06:20 +00:00
### Authorization
2021-06-09 15:10:05 +00:00
Authorization uses the same engine as the GitLab application (and GitLab.com).
If you've signed in to GitLab and use GraphiQL, all queries are performed as
you, the signed in user. For more information, read the
2021-06-28 15:08:03 +00:00
[GitLab API documentation ](../index.md#authentication ).
2019-11-22 09:06:20 +00:00
### Mutations
2021-06-09 15:10:05 +00:00
Mutations make changes to data. We can update, delete, or create new records.
Mutations generally use InputTypes and variables, neither of which appear here.
2019-11-22 09:06:20 +00:00
Mutations have:
- Inputs. For example, arguments, such as which emoji you'd like to award,
2021-06-09 15:10:05 +00:00
and to which object.
2019-11-22 09:06:20 +00:00
- Return statements. That is, what you'd like to get back when it's successful.
- Errors. Always ask for what went wrong, just in case.
#### Creation mutations
Example: Let's have some tea - add a `:tea:` reaction emoji to an issue.
```graphql
mutation {
2020-06-23 12:09:20 +00:00
awardEmojiAdd(input: { awardableId: "gid://gitlab/Issue/27039960",
2019-11-22 09:06:20 +00:00
name: "tea"
}) {
awardEmoji {
name
description
unicode
emoji
unicodeVersion
user {
name
}
}
errors
}
}
```
2021-06-09 15:10:05 +00:00
Example: Add a comment to the issue. In this example, we use the ID of the
`GitLab.com` issue. If you're using a local instance, you must get the ID of an
issue you can write to.
2019-11-22 09:06:20 +00:00
```graphql
mutation {
createNote(input: { noteableId: "gid://gitlab/Issue/27039960",
body: "*sips tea*"
}) {
note {
id
body
discussion {
id
2019-11-27 09:06:29 +00:00
}
2019-11-22 09:06:20 +00:00
}
errors
}
}
```
#### Update mutations
2021-06-09 15:10:05 +00:00
When you see the result `id` of the note you created, take a note of it. Let's
edit it to sip faster.
2019-11-22 09:06:20 +00:00
```graphql
mutation {
2020-08-21 00:10:44 +00:00
updateNote(input: { id: "gid://gitlab/Note/< note ID > ",
2019-11-22 09:06:20 +00:00
body: "*SIPS TEA*"
}) {
note {
id
body
}
errors
}
}
```
#### Deletion mutations
2021-06-09 15:10:05 +00:00
Let's delete the comment, because our tea is all gone.
2019-11-22 09:06:20 +00:00
```graphql
mutation {
2020-08-21 00:10:44 +00:00
destroyNote(input: { id: "gid://gitlab/Note/< note ID > " }) {
2019-11-22 09:06:20 +00:00
note {
id
body
}
errors
}
}
```
You should get something like the following output:
```json
{
"data": {
"destroyNote": {
"errors": [],
"note": null
}
}
}
```
We've asked for the note details, but it doesn't exist anymore, so we get `null` .
More about mutations:
2021-06-09 15:10:05 +00:00
[GraphQL Documentation ](https://graphql.org/learn/queries/#mutations ).
2019-11-22 09:06:20 +00:00
### Introspective queries
Clients can query the GraphQL endpoint for information about its own schema.
by making an [introspective query ](https://graphql.org/learn/introspection/ ).
2021-06-09 15:10:05 +00:00
The [GraphiQL Query Explorer ](https://gitlab.com/-/graphql-explorer ) uses an
introspection query to:
2019-11-22 09:06:20 +00:00
2021-06-09 15:10:05 +00:00
- Gain knowledge about our GraphQL schema.
- Do autocompletion.
- Provide its interactive `Docs` tab.
2019-11-22 09:06:20 +00:00
Example: Get all the type names in the schema.
```graphql
{
__schema {
types {
name
}
}
}
```
2021-06-09 15:10:05 +00:00
Example: Get all the fields associated with Issue. `kind` tells us the enum
value for the type, like `OBJECT` , `SCALAR` or `INTERFACE` .
2019-11-22 09:06:20 +00:00
```graphql
query IssueTypes {
__type(name: "Issue") {
kind
name
fields {
name
description
type {
name
}
}
}
}
```
More about introspection:
2021-06-09 15:10:05 +00:00
[GraphQL documentation ](https://graphql.org/learn/introspection/ )
2019-11-22 09:06:20 +00:00
2021-07-07 09:08:35 +00:00
### Query complexity
The calculated [complexity score and limit ](index.md#max-query-complexity ) for a query can be revealed to clients by
querying for `queryComplexity` .
```graphql
query {
queryComplexity {
score
limit
}
project(fullPath: "gitlab-org/graphql-sandbox") {
name
}
}
```
2019-11-22 09:06:20 +00:00
## Sorting
2021-06-09 15:10:05 +00:00
Some of the GitLab GraphQL endpoints allow you to specify how to sort a
collection of objects. You can only sort by what the schema allows you to.
2019-11-22 09:06:20 +00:00
Example: Issues can be sorted by creation date:
```graphql
query {
2019-12-11 06:07:52 +00:00
project(fullPath: "gitlab-org/graphql-sandbox") {
name
issues(sort: created_asc) {
nodes {
title
createdAt
2019-11-22 09:06:20 +00:00
}
}
}
2019-12-11 06:07:52 +00:00
}
2019-11-22 09:06:20 +00:00
```
## Pagination
2021-06-09 15:10:05 +00:00
Pagination is a way of only asking for a subset of the records, such as the
first ten. If we want more of them, we can make another request for the next
ten from the server in the form of something like `please give me the next ten records` .
2019-11-22 09:06:20 +00:00
2021-06-09 15:10:05 +00:00
By default, the GitLab GraphQL API returns 100 records per page. To change this
behavior, use `first` or `last` arguments. Both arguments take a value, so
`first: 10` returns the first ten records, and `last: 10` the last ten records.
There is a limit on how many records are returned per page, which is generally
`100` .
2019-11-22 09:06:20 +00:00
2021-06-09 15:10:05 +00:00
Example: Retrieve only the first two issues (slicing). The `cursor` field gives
us a position from which we can retrieve further records relative to that one.
2019-11-22 09:06:20 +00:00
```graphql
query {
project(fullPath: "gitlab-org/graphql-sandbox") {
name
issues(first: 2) {
edges {
node {
title
}
}
2019-12-11 06:07:52 +00:00
pageInfo {
endCursor
hasNextPage
2019-11-22 09:06:20 +00:00
}
}
}
}
```
2021-06-09 15:10:05 +00:00
Example: Retrieve the next three. (The cursor value
2019-11-22 09:06:20 +00:00
`eyJpZCI6IjI3MDM4OTMzIiwiY3JlYXRlZF9hdCI6IjIwMTktMTEtMTQgMDU6NTY6NDQgVVRDIn0`
2021-06-09 15:10:05 +00:00
could be different, but it's the `cursor` value returned for the second issue
returned above.)
2019-11-22 09:06:20 +00:00
```graphql
query {
project(fullPath: "gitlab-org/graphql-sandbox") {
name
issues(first: 3, after: "eyJpZCI6IjI3MDM4OTMzIiwiY3JlYXRlZF9hdCI6IjIwMTktMTEtMTQgMDU6NTY6NDQgVVRDIn0") {
edges {
node {
title
}
cursor
}
pageInfo {
endCursor
hasNextPage
}
}
}
}
```
2021-06-09 15:10:05 +00:00
More about pagination and cursors:
[GraphQL documentation ](https://graphql.org/learn/pagination/ )