1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
|
# Getting started with GitLab GraphQL API
This guide demonstrates basic usage of GitLab's GraphQL API.
See the [GraphQL API StyleGuide](../../development/api_graphql_styleguide.md) for implementation details
aimed at developers who wish to work on developing the API itself.
## Running examples
The examples documented here can be run using:
- The command line.
- GraphiQL.
### Command line
You can run GraphQL queries in a `curl` request on the command line on your local machine.
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.
Example:
```sh
GRAPHQL_TOKEN = <your-token>
curl 'http://gitlab.com/api/graphql' --header "Authorization: Bearer $GRAPHQL_TOKEN" --header "Content-Type: application/json" --request POST --data "{\"query\": \"query {currentUser {name}}\"}
```
### GraphiQL
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.
The examples below:
- Can be run directly against GitLab 11.0 or later, though some of the types and fields
may not be supported in older versions.
- Will work against GitLab.com without any further setup. Make sure you are signed in and
navigate to the [GraphiQL Explorer](https://www.gitlab.com/-/graphql-explorer).
If you want to run the queries locally, or on a self-managed instance,
you will need to either:
- Create the `gitlab-org` group with a project called `graphql-sandbox` under it. Create
several issues within the project.
- Edit the queries to replace `gitlab-org/graphql-sandbox` with your own group and project.
Please refer to [running GraphiQL](index.md#graphiql) for more information.
NOTE: **Note:**
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.
NOTE: **Note:**
In the GitLab GraphQL API, `id` generally refers to a global ID,
which is an object identifier in the format of `gid://gitlab/Issue/123`.
[GitLab's GraphQL Schema](reference/index.md) outlines which objects and fields are
available for clients to query and their corresponding data types.
Example: Get only the names of all the projects the currently logged in user can access (up to a limit, more on that later)
in the group `gitlab-org`.
```graphql
query {
group(fullPath: "gitlab-org") {
id
name
projects {
nodes {
name
}
}
}
}
```
Example: Get a specific project and the title of Issue #2.
```graphql
query {
project(fullPath: "gitlab-org/graphql-sandbox") {
name
issue(iid: "2") {
title
}
}
}
```
### The root node
Any field defined in [`QueryType`](app/graphql/types/query_type.rb) will be exposed as a root node.
When retrieving child nodes use:
- the `edges { node { } }` syntax.
- the short form `nodes { }` syntax.
Underneath it all is a graph we are traversing, hence the name GraphQL.
Example: Get a project (only its name) and the titles of all its issues.
```graphql
query {
project(fullPath: "gitlab-org/graphql-sandbox") {
name
issues {
nodes {
title
description
}
}
}
}
```
More on schema definitions:
[graphql-ruby docs](https://graphql-ruby.org/schema/definition)
More about queries:
[GraphQL docs](https://graphql.org/learn/queries/) and
[graphql-ruby docs](https://graphql-ruby.org/queries/executing_queries)
### Authorization
Authorization uses the same engine as the Rails app. So if you've signed in to GitLab
and use GraphiQL, all queries will be performed as you, the signed in user.
See the [authorization section](../../development/api_graphql_styleguide.html#authorization) of the StyleGuide
for implementation details.
### Resolvers
A resolver is how we define how the records requested by the client are retrieved, collected,
and assembled into the response.
The [GraphQL API StyleGuide](../../development/api_graphql_styleguide.md#resolvers) has more details
about the implementation of resolvers.
More about resolvers:
[GraphQL Docs](https://graphql.org/learn/execution/) and
[graphql-ruby docs](https://graphql-ruby.org/fields/resolvers.html)
### Mutations
Mutations make changes to data. We can update, delete, or create new records. Mutations
generally use InputTypes and variables, neither of which appear here.
Mutations have:
- Inputs. For example, arguments, such as which emoji you'd like to award,
and to which object.
- 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 {
addAwardEmoji(input: { awardableId: "gid://gitlab/Issue/27039960",
name: "tea"
}) {
awardEmoji {
name
description
unicode
emoji
unicodeVersion
user {
name
}
}
errors
}
}
```
Example: Add a comment to the issue (we're using the ID of the `GitLab.com` issue - but
if you're using a local instance, you'll need to get the ID of an issue you can write to).
```graphql
mutation {
createNote(input: { noteableId: "gid://gitlab/Issue/27039960",
body: "*sips tea*"
}) {
note {
id
body
discussion {
id
}
}
errors
}
}
```
#### Update mutations
When you see the result `id` of the note you created - take a note of it. Now let's edit it to sip faster!
```graphql
mutation {
updateNote(input: { id: "gid://gitlab/Note/<note id>",
body: "*SIPS TEA*"
}) {
note {
id
body
}
errors
}
}
```
#### Deletion mutations
Let's delete the comment, since our tea is all gone.
```graphql
mutation {
destroyNote(input: { id: "gid://gitlab/Note/<note id>" }) {
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`.
The [GraphQL API StyleGuide](../../development/api_graphql_styleguide.md#mutations) has more details
about implementation of mutations.
More about mutations:
[GraphQL Docs](https://graphql.org/learn/queries/#mutations) and
[graphql-ruby docs](https://graphql-ruby.org/mutations/mutation_classes.html)
### Introspective queries
Clients can query the GraphQL endpoint for information about its own schema.
by making an [introspective query](https://graphql.org/learn/introspection/).
It is through an introspection query that the [GraphiQL Query Explorer](https://gitlab.com/-/graphql-explorer)
gets all of its knowledge about our GraphQL schema to do autocompletion and provide
its interactive `Docs` tab.
Example: Get all the type names in the schema.
```graphql
{
__schema {
types {
name
}
}
}
```
Example: Get all the fields associated with Issue.
`kind` tells us the enum value for the type, like `OBJECT`, `SCALAR` or `INTERFACE`.
```graphql
query IssueTypes {
__type(name: "Issue") {
kind
name
fields {
name
description
type {
name
}
}
}
}
```
More about introspection:
[GraphQL docs](https://graphql.org/learn/introspection/) and
[graphql-ruby docs](https://graphql-ruby.org/schema/introspection.html)
## Sorting
Some of GitLab's GraphQL endpoints allow you to specify how you'd like a collection of
objects to be sorted. You can only sort by what the schema allows you to.
Example: Issues can be sorted by creation date:
```graphql
query {
project(fullPath: "gitlab-org/graphql-sandbox") {
name
issues(sort: created_asc) {
nodes {
title
createdAt
}
}
}
}
```
## Pagination
Pagination is a way of only asking for a subset of the records (say, the first 10).
If we want more of them, we can make another request for the next 10 from the server
(in the form of something like "please give me the next 10 records").
By default, GitLab's GraphQL API will return only the first 100 records of any collection.
This can be changed by using `first` or `last` arguments. Both arguments take a value,
so `first: 10` will return the first 10 records, and `last: 10` the last 10 records.
Example: Retrieve only the first 2 issues (slicing). The `cursor` field gives us a position from which
we can retrieve further records relative to that one.
```graphql
query {
project(fullPath: "gitlab-org/graphql-sandbox") {
name
issues(first: 2) {
edges {
node {
title
}
}
pageInfo {
endCursor
hasNextPage
}
}
}
}
```
Example: Retrieve the next 3. (The cursor value
`eyJpZCI6IjI3MDM4OTMzIiwiY3JlYXRlZF9hdCI6IjIwMTktMTEtMTQgMDU6NTY6NDQgVVRDIn0`
could be different, but it's the `cursor` value returned for the second issue returned above.)
```graphql
query {
project(fullPath: "gitlab-org/graphql-sandbox") {
name
issues(first: 3, after: "eyJpZCI6IjI3MDM4OTMzIiwiY3JlYXRlZF9hdCI6IjIwMTktMTEtMTQgMDU6NTY6NDQgVVRDIn0") {
edges {
node {
title
}
cursor
}
pageInfo {
endCursor
hasNextPage
}
}
}
}
```
More on pagination and cursors:
[GraphQL docs](https://graphql.org/learn/pagination/) and
[graphql-ruby docs](https://graphql-ruby.org/relay/connections.html#cursors)
|