Skip to content

G
gitlab-ce
Commit 9718c9a8 authored by Craig Norris's avatar Craig Norris
Browse files
Options

Merge branch 'docs-aqualls-clean-starting-page' into 'master' 

Quick polish of the GraphQL get-started page

See merge request gitlab-org/gitlab!62952
parents 731b929e ee226412
Show whitespace changes
Inline Side-by-side
Showing with 67 additions and 56 deletions
doc/api/graphql/getting_started.md
View file @ 9718c9a8
......@@ -4,12 +4,13 @@ group: Ecosystem
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
---
# Getting started with GitLab GraphQL API
# Get started with GitLab GraphQL API **(FREE)**
This guide demonstrates basic usage of the GitLab GraphQL API.
See the [GraphQL API style guide](../../development/api_graphql_styleguide.md) for implementation details
aimed at developers who wish to work on developing the API itself.
Read the [GraphQL API style guide](../../development/api_graphql_styleguide.md)
for implementation details aimed at developers who wish to work on developing
the API itself.
## Running examples
......@@ -20,10 +21,11 @@ The examples documented here can be run using:
### 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.
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.
Example:
......@@ -36,24 +38,26 @@ curl "https://gitlab.com/api/graphql" --header "Authorization: Bearer $GRAPHQL_T
### 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.
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.
- 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).
- 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).
If you want to run the queries locally, or on a self-managed instance,
you must either:
If you want to run the queries locally, or on a self-managed instance, you must
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.
- 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.
Please refer to [running GraphiQL](index.md#graphiql) for more information.
Refer to [running GraphiQL](index.md#graphiql) for more information.
NOTE:
If you are running GitLab 11.0 to 12.0, enable the `graphql`
......@@ -74,8 +78,8 @@ which is an object identifier in the format of `"gid://gitlab/Issue/123"`.
[GitLab 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`.
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`.
```graphql
query {
......@@ -108,12 +112,12 @@ query {
When retrieving child nodes use:
- the `edges { node { } }` syntax.
- the short form `nodes { }` syntax.
- 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.
Example: Get the name of a project, and the titles of all its issues.
```graphql
query {
......@@ -130,23 +134,24 @@ query {
```
More about queries:
[GraphQL docs](https://graphql.org/learn/queries/)
[GraphQL documentation](https://graphql.org/learn/queries/)
### Authorization
Authorization uses the same engine as the GitLab application (and GitLab.com). So if you've signed in to GitLab
and use GraphiQL, all queries are performed as you, the signed in user. For more information, see the
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
[GitLab API documentation](../README.md#authentication).
### 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 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.
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.
......@@ -174,8 +179,9 @@ mutation {
}
```
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 must get the ID of an issue you can write to).
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.
```graphql
mutation {
......@@ -196,7 +202,8 @@ mutation {
#### 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!
When you see the result `id` of the note you created, take a note of it. Let's
edit it to sip faster.
```graphql
mutation {
......@@ -214,7 +221,7 @@ mutation {
#### Deletion mutations
Let's delete the comment, since our tea is all gone.
Let's delete the comment, because our tea is all gone.
```graphql
mutation {
......@@ -244,16 +251,18 @@ You should get something like the following output:
We've asked for the note details, but it doesn't exist anymore, so we get `null`.
More about mutations:
[GraphQL Docs](https://graphql.org/learn/queries/#mutations).
[GraphQL Documentation](https://graphql.org/learn/queries/#mutations).
### Introspective queries
Clients can query the GraphQL endpoint for information about its own schema.
by making an [introspective query](https://graphql.org/learn/introspection/).
The [GraphiQL Query Explorer](https://gitlab.com/-/graphql-explorer) uses an
introspection query to:
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.
- Gain knowledge about our GraphQL schema.
- Do autocompletion.
- Provide its interactive `Docs` tab.
Example: Get all the type names in the schema.
......@@ -267,8 +276,8 @@ Example: Get all the type names in the schema.
}
```
Example: Get all the fields associated with Issue.
`kind` tells us the enum value for the type, like `OBJECT`, `SCALAR` or `INTERFACE`.
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 {
......@@ -287,12 +296,12 @@ query IssueTypes {
```
More about introspection:
[GraphQL docs](https://graphql.org/learn/introspection/)
[GraphQL documentation](https://graphql.org/learn/introspection/)
## Sorting
Some of the GitLab 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.
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.
Example: Issues can be sorted by creation date:
......@@ -312,17 +321,18 @@ query {
## 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").
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`.
By default, the GitLab GraphQL API returns 100 records per page.
This can be changed by using `first` or `last` arguments. Both arguments take a value,
so `first: 10` returns the first 10 records, and `last: 10` the last 10 records.
There is a limit on how many records will be returned per page, which is generally `100`.
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`.
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.
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.
```graphql
query {
......@@ -343,9 +353,10 @@ query {
}
```
Example: Retrieve the next 3. (The cursor value
Example: Retrieve the next three. (The cursor value
`eyJpZCI6IjI3MDM4OTMzIiwiY3JlYXRlZF9hdCI6IjIwMTktMTEtMTQgMDU6NTY6NDQgVVRDIn0`
could be different, but it's the `cursor` value returned for the second issue returned above.)
could be different, but it's the `cursor` value returned for the second issue
returned above.)
```graphql
query {
......@@ -367,5 +378,5 @@ query {
}
```
More on pagination and cursors:
[GraphQL docs](https://graphql.org/learn/pagination/)
More about pagination and cursors:
[GraphQL documentation](https://graphql.org/learn/pagination/)
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7