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

Quick polish of the GraphQL get-started page

See merge request gitlab-org/gitlab!62952

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,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/)