diff options
Diffstat (limited to 'doc/api/README.md')
| -rw-r--r-- | doc/api/README.md | 17 |
1 files changed, 10 insertions, 7 deletions
diff --git a/doc/api/README.md b/doc/api/README.md index b07f14b5a7a..82cce57f47b 100644 --- a/doc/api/README.md +++ b/doc/api/README.md @@ -156,7 +156,7 @@ for example, without needing to explicitly pass an access token. With a few API endpoints you can use a [GitLab CI/CD job token](../user/project/new_ci_build_permissions_model.md#job-token) to authenticate with the API: -- [Get job artifacts](jobs.md#get-job-artifacts) +- [Get job artifacts](job_artifacts.md#get-job-artifacts) - [Pipeline triggers](pipeline_triggers.md) - [Release creation](releases/index.md#create-a-release) @@ -218,6 +218,7 @@ Only available to [administrators](../user/permissions.md). All API requests support performing an API call as if you were another user, provided you are 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. You need to pass the `sudo` parameter either via query string or a header with an ID/username of the user you want to perform the operation as. If passed as a header, the @@ -337,10 +338,10 @@ In the example below, we list 50 [namespaces](namespaces.md) per page. curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/namespaces?per_page=50" ``` -#### Pagination Link header +#### Pagination `Link` header -[Link headers](https://www.w3.org/wiki/LinkHeader) are sent back with each -response. They have `rel` set to prev/next/first/last and contain the relevant +[`Link` headers](https://www.w3.org/wiki/LinkHeader) are sent back with each +response. They have `rel` set to `prev`/`next`/`first`/`last` and contain the relevant URL. Please use these links instead of generating your own URLs. In the cURL example below, we limit the output to 3 items per page (`per_page=3`) @@ -423,12 +424,14 @@ Status: 200 OK ``` CAUTION: **Deprecation:** -The `Links` Header will be removed in GitLab 14.0 to be aligned with the [W3C `Link` specification](https://www.w3.org/wiki/LinkHeader) +The `Links` header will be removed in GitLab 14.0 to be aligned with the [W3C `Link` specification](https://www.w3.org/wiki/LinkHeader). +The `Link` header was [added in GitLab 13.1](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/33714) +and should be used instead. The link to the next page contains an additional filter `id_after=42` which excludes records we have retrieved already. Note the type of filter depends on the `order_by` option used and we may have more than one additional filter. -When the end of the collection has been reached and there are no additional records to retrieve, the `Links` header is absent and the resulting array is empty. +When the end of the collection has been reached and there are no additional records to retrieve, the `Link` header is absent and the resulting array is empty. We recommend using only the given link to retrieve the next page instead of building your own URL. Apart from the headers shown, we don't expose additional pagination headers. @@ -544,7 +547,7 @@ https://gitlab.example.com/api/v4/projects/import ### Array of hashes -`variables` is a parameter of type `array` containing hash key/value pairs `[{ 'key' => 'UPLOAD_TO_S3', 'value' => 'true' }]`: +`variables` is a parameter of type `array` containing hash key/value pairs `[{ 'key': 'UPLOAD_TO_S3', 'value': 'true' }]`: ```shell curl --globoff --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ |