diff options
Diffstat (limited to 'doc/api/graphql/getting_started.md')
| -rw-r--r-- | doc/api/graphql/getting_started.md | 127 |
1 files changed, 70 insertions, 57 deletions
diff --git a/doc/api/graphql/getting_started.md b/doc/api/graphql/getting_started.md index b48ce48f6c3..85b36346167 100644 --- a/doc/api/graphql/getting_started.md +++ b/doc/api/graphql/getting_started.md @@ -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,38 +21,43 @@ 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: ```shell GRAPHQL_TOKEN=<your-token> -curl "https://gitlab.com/api/graphql" --header "Authorization: Bearer $GRAPHQL_TOKEN" --header "Content-Type: application/json" --request POST --data "{\"query\": \"query {currentUser {name}}\"}" +curl "https://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. +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` @@ -72,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 { @@ -106,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 { @@ -128,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. @@ -172,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 { @@ -194,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 { @@ -212,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 { @@ -242,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. @@ -265,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 { @@ -285,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: @@ -310,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 { @@ -341,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 { @@ -365,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/) |