Add latest changes from gitlab-org/gitlab@master

1 files changed, 59 insertions, 61 deletions

diff --git a/doc/api/README.md b/doc/api/README.md
index 7332600c972..b310ca0fd7d 100644
--- a/doc/api/README.md
+++ b/doc/api/README.md
@@ -6,14 +6,10 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 
 # API Docs
 
-Automate GitLab by using a simple and powerful API.
+Use the GitLab [REST](http://spec.openapis.org/oas/v3.0.3) API to automate GitLab.
 
-The main GitLab API is a [REST](http://spec.openapis.org/oas/v3.0.3)
-API. Because of this, the documentation in this section assumes that you're
-familiar with REST concepts.
-
-There's also a partial [OpenAPI definition](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/api/openapi/openapi.yaml),
-which allows you to test the API directly from the GitLab user interface.
+You can also use a partial [OpenAPI definition](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/api/openapi/openapi.yaml),
+to test the API directly from the GitLab user interface.
 Contributions are welcome.
 
 ## Available API resources
@@ -31,52 +27,54 @@ GitLab provides an [SCIM API](scim.md) that both implements
 [the RFC7644 protocol](https://tools.ietf.org/html/rfc7644) and provides the
 `/Users` endpoint. The base URL is `/api/scim/v2/groups/:group_path/Users/`.
 
-## Road to GraphQL
-
-[GraphQL](graphql/index.md) is available in GitLab, which allows for the
-deprecation of controller-specific endpoints.
+## GraphQL API
 
-GraphQL has several benefits, including:
+A [GraphQL](graphql/index.md) API is available in GitLab.
 
-- We avoid having to maintain two different APIs.
-- Callers of the API can request only what they need.
-- It's versioned by default.
+With GraphQL, you can make an API request for only what you need,
+and it's versioned by default.
 
 GraphQL co-exists with the current v4 REST API. If we have a v5 API, this should
 be a compatibility layer on top of GraphQL.
 
-Although there were some patenting and licensing concerns with GraphQL, these
-have been resolved to our satisfaction by the relicensing of the reference
-implementations under MIT, and the use of the OWF license for the GraphQL
-specification.
+There were some patenting and licensing concerns with GraphQL. However, these
+have been resolved to our satisfaction. The reference implementations
+were re-licensed under MIT, and the OWF license used for the GraphQL specification.
+
+When GraphQL is fully implemented, GitLab:
+
+- Can delete controller-specific endpoints.
+- Will no longer maintain two different APIs.
 
 ## Compatibility guidelines
 
-The HTTP API is versioned using a single number, (currently _4_). This number
+The HTTP API is versioned with a single number, which is currently `4`. This number
 symbolizes the major version number, as described by [SemVer](https://semver.org/).
-Because of this, backwards-incompatible changes require this version number to
-change. However, the minor version isn't explicit, allowing for a stable API
-endpoint. This also means that new features can be added to the API in the same
+Because of this, backward-incompatible changes require this version number to
+change.
+
+The minor version isn't explicit, which allows for a stable API
+endpoint. New features can be added to the API in the same
 version number.
 
-New features and bug fixes are released in tandem with a new GitLab, and apart
-from incidental patch and security releases, are released on the 22nd of each
-month. Backward incompatible changes (for example, endpoints removal and
-parameters removal), and removal of entire API versions are done in tandem with
-a major point release of GitLab itself. All deprecations and changes between two
-versions should be listed in the documentation. For the changes between v3 and
-v4, see the [v3 to v4 documentation](v3_to_v4.md).
+New features and bug fixes are released in tandem with GitLab. Apart
+from incidental patch and security releases, GitLab is released on the 22nd of each
+month. Backward-incompatible changes (for example, endpoint and parameter removal),
+and removal of entire API versions are done in tandem with major GitLab releases.
+
+All deprecations and changes between versions are in the documentation.
+For the changes between v3 and v4, see the [v3 to v4 documentation](v3_to_v4.md).
 
 ### Current status
 
 Only API version v4 is available. Version v3 was removed in
 [GitLab 11.0](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/36819).
 
-## Basic usage
+## How to use the API
 
-API requests should be prefixed with both `api` and the API version. The API
+API requests must include both `api` and the API version. The API
 version is defined in [`lib/api.rb`](https://gitlab.com/gitlab-org/gitlab/tree/master/lib/api/api.rb).
-For example, the root of the v4 API is at `/api/v4`. The following sections illustrate different uses:
+For example, the root of the v4 API is at `/api/v4`.
 
 ### Valid API request
 
@@ -87,7 +85,7 @@ curl "https://gitlab.example.com/api/v4/projects"
 ```
 
 The API uses JSON to serialize data. You don't need to specify `.json` at the
-end of an API URL.
+end of the API URL.
 
 ### API request to expose HTTP response headers
 
@@ -99,7 +97,7 @@ HTTP/2 200
 ...
 ```
 
-This can help you investigate an unexpected response.
+This request can help you investigate an unexpected response.
 
 ### API request that includes the exit code
 
@@ -110,16 +108,16 @@ curl --fail "https://gitlab.example.com/api/v4/does-not-exist"
 curl: (22) The requested URL returned error: 404
 ```
 
-The HTTP exit code can help you diagnose the success or failure of your REST call.
+The HTTP exit code can help you diagnose the success or failure of your REST request.
 
 ## Authentication
 
 Most API requests require authentication, or only return public data when
-authentication isn't provided. For cases where it isn't required, this is
-mentioned in the documentation for each individual endpoint (for example, the
-[`/projects/:id` endpoint](projects.md#get-single-project)).
+authentication isn't provided. When authentication is not required, the documentation
+for each endpoint specifies this. For example, the
+[`/projects/:id` endpoint](projects.md#get-single-project) does not require authentication.
 
-There are several methods you can use to authenticate with the GitLab API:
+There are several ways you can authenticate with the GitLab API:
 
 - [OAuth2 tokens](#oauth2-tokens)
 - [Personal access tokens](../user/profile/personal_access_tokens.md)
@@ -131,13 +129,13 @@ NOTE:
 Project access tokens are supported for self-managed instances on Free and
 higher. They're also supported on GitLab.com Bronze and higher.
 
-For administrators who want to authenticate with the API as a specific user, or who want
-to build applications or scripts that do so, the following options are available:
+If you are an administrator, you or your application can authenticate as a specific user.
+To do so, use:
 
 - [Impersonation tokens](#impersonation-tokens)
 - [Sudo](#sudo)
 
-If authentication information is invalid or omitted, GitLab returns an error
+If authentication information is not valid or is missing, GitLab returns an error
 message with a status code of `401`:
 
 ```json
@@ -195,8 +193,8 @@ API uses this cookie for authentication if it's present. Using the API to
 generate a new session cookie isn't supported.
 
 The primary user of this authentication method is the web frontend of GitLab
-itself, which can, for example, use the API as the authenticated user to get a
-list of their projects without needing to explicitly pass an access token.
+itself. The web frontend can use the API as the authenticated user to get a
+list of projects without explicitly passing an access token.
 
 ### GitLab CI/CD job token
 
@@ -245,15 +243,15 @@ tries to steal tokens from other jobs.
 
 ### Impersonation tokens
 
-Impersonation tokens are a type of [personal access token](../user/profile/personal_access_tokens.md)
-that can be created only by an administrator for a specific user. They can be
-useful if you want to build applications or scripts that authenticate with the
+Impersonation tokens are a type of [personal access token](../user/profile/personal_access_tokens.md).
+They can be created only by an administrator, and are used to authenticate with the
 API as a specific user.
 
-They're an alternative to directly using the user's password (or one of their
-personal access tokens), and to using the [Sudo](#sudo) feature, as the user's
-(or administrator's in the case of Sudo) password or token may not be known, or may
-change over time.
+Use impersonation tokens an alternative to:
+
+- The user's password or one of their personal access tokens.
+- The [Sudo](#sudo) feature. The user's or administrator's password or token
+  may not be known, or may change over time.
 
 For more information, see the [users API](users.md#create-an-impersonation-token)
 documentation.
@@ -298,7 +296,7 @@ To re-enable impersonation, remove this configuration, and then restart GitLab.
 
 ### Sudo
 
-All API requests support performing an API call as if you were another user,
+All API requests support performing an API request as if you were another user,
 provided you're authenticated as an administrator with an OAuth or personal
 access token that has the `sudo` scope. The API requests are executed with the
 permissions of the impersonated user.
@@ -337,7 +335,7 @@ returned with a status code of `404`:
 }
 ```
 
-Example of a valid API call and a request using cURL with sudo request,
+Example of a valid API request and a request using cURL with sudo request,
 providing a username:
 
 ```plaintext
@@ -348,7 +346,7 @@ GET /projects?private_token=<your_access_token>&sudo=username
 curl --header "PRIVATE-TOKEN: <your_access_token>" --header "Sudo: username" "https://gitlab.example.com/api/v4/projects"
 ```
 
-Example of a valid API call and a request using cURL with sudo request,
+Example of a valid API request and a request using cURL with sudo request,
 providing an ID:
 
 ```plaintext
@@ -362,7 +360,7 @@ curl --header "PRIVATE-TOKEN: <your_access_token>" --header "Sudo: 23" "https://
 ## Status codes
 
 The API is designed to return different status codes according to context and
-action. This way, if a request results in an error, the caller is able to get
+action. This way, if a request results in an error, you can get
 insight into what went wrong.
 
 The following table gives an overview of how the API functions generally behave.
@@ -543,7 +541,7 @@ The `:id` path parameter needs to be replaced with the project ID, and the
 `:group_id` needs to be replaced with the ID of the group. The colons `:`
 shouldn't be included.
 
-The resulting cURL call for a project with ID `5` and a group ID of `17` is then:
+The resulting cURL request for a project with ID `5` and a group ID of `17` is then:
 
 ```shell
 curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/share/17"
@@ -556,7 +554,7 @@ the URL-encoded path parameters.
 
 ## Namespaced path encoding
 
-If using namespaced API calls, make sure that the `NAMESPACE/PROJECT_PATH` is
+If using namespaced API requests, make sure that the `NAMESPACE/PROJECT_PATH` is
 URL-encoded.
 
 For example, `/` is represented by `%2F`:
@@ -606,7 +604,7 @@ using a payload body instead.
 
 ## Encoding API parameters of `array` and `hash` types
 
-We can call the API with `array` and `hash` types parameters as follows:
+You can request the API with `array` and `hash` types parameters:
 
 ### `array`
 
@@ -664,8 +662,8 @@ usually used instead of `id` to fetch the resource.
 For example, suppose a project with `id: 42` has an issue with `id: 46` and
 `iid: 5`. In this case:
 
-- A valid API call to retrieve the issue is `GET /projects/42/issues/5`.
-- An invalid API call to retrieve the issue is `GET /projects/42/issues/46`.
+- A valid API request to retrieve the issue is `GET /projects/42/issues/5`.
+- An invalid API request to retrieve the issue is `GET /projects/42/issues/46`.
 
 Not all resources with the `iid` field are fetched by `iid`. For guidance
 regarding which field to use, see the documentation for the specific resource.