diff options
Diffstat (limited to 'doc/api/graphql/getting_started.md')
| -rw-r--r-- | doc/api/graphql/getting_started.md | 26 |
1 files changed, 13 insertions, 13 deletions
diff --git a/doc/api/graphql/getting_started.md b/doc/api/graphql/getting_started.md index 8501e76b5aa..ca2b7989700 100644 --- a/doc/api/graphql/getting_started.md +++ b/doc/api/graphql/getting_started.md @@ -1,12 +1,12 @@ --- stage: none group: unassigned -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/#designated-technical-writers +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 -This guide demonstrates basic usage of GitLab's GraphQL API. +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. @@ -29,7 +29,7 @@ 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 @@ -41,11 +41,11 @@ 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 +- 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 will need to either: +you must either: - Create the `gitlab-org` group with a project called `graphql-sandbox` under it. Create several issues within the project. @@ -53,7 +53,7 @@ several issues within the project. Please refer to [running GraphiQL](index.md#graphiql) for more information. -NOTE: **Note:** +NOTE: If you are running GitLab 11.0 to 12.0, enable the `graphql` [feature flag](../features.md#set-or-create-a-feature). @@ -64,12 +64,12 @@ The GitLab GraphQL API can be used to perform: - Queries for data retrieval. - [Mutations](#mutations) for creating, updating, and deleting data. -NOTE: **Note:** +NOTE: 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"`. -[GitLab's GraphQL Schema](reference/index.md) outlines which objects and fields are +[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) @@ -133,7 +133,7 @@ More about 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 will be performed as you, the signed in user. For more information, see the +and use GraphiQL, all queries are performed as you, the signed in user. For more information, see the [GitLab API documentation](../README.md#authentication). ### Mutations @@ -173,7 +173,7 @@ 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'll need to get the ID of an issue you can write to). +if you're using a local instance, you must get the ID of an issue you can write to). ```graphql mutation { @@ -289,7 +289,7 @@ More about introspection: ## Sorting -Some of GitLab's GraphQL endpoints allow you to specify how you'd like a collection of +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. Example: Issues can be sorted by creation date: @@ -314,9 +314,9 @@ Pagination is a way of only asking for a subset of the records (say, the first 1 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. +By default, the GitLab GraphQL API returns 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. +so `first: 10` returns 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. |