summaryrefslogtreecommitdiff
path: root/doc/api/README.md
diff options
context:
space:
mode:
Diffstat (limited to 'doc/api/README.md')
-rw-r--r--doc/api/README.md52
1 files changed, 26 insertions, 26 deletions
diff --git a/doc/api/README.md b/doc/api/README.md
index 82cce57f47b..53df4114a71 100644
--- a/doc/api/README.md
+++ b/doc/api/README.md
@@ -4,6 +4,8 @@ Automate GitLab via a simple and powerful API.
The main GitLab API is a [REST](https://en.wikipedia.org/wiki/Representational_state_transfer) API. Therefore, documentation in this section assumes knowledge of REST concepts.
+There is 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. Contributions are welcome.
+
## Available API resources
For a list of the available resources and their endpoints, see
@@ -121,7 +123,7 @@ Read more about [GitLab as an OAuth2 provider](oauth2.md).
### Personal/project access tokens
Access tokens can be used to authenticate with the API by passing it in either the `private_token` parameter
-or the `Private-Token` header.
+or the `PRIVATE-TOKEN` header.
Example of using the personal/project access token in a parameter:
@@ -132,7 +134,7 @@ curl "https://gitlab.example.com/api/v4/projects?private_token=<your_access_toke
Example of using the personal/project access token in a header:
```shell
-curl --header "Private-Token: <your_access_token>" "https://gitlab.example.com/api/v4/projects"
+curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects"
```
You can also use personal/project access tokens with OAuth-compliant headers:
@@ -176,7 +178,7 @@ For more information, refer to the
[users API](users.md#create-an-impersonation-token) docs.
Impersonation tokens are used exactly like regular personal access tokens, and can be passed in either the
-`private_token` parameter or the `Private-Token` header.
+`private_token` parameter or the `PRIVATE-TOKEN` header.
#### Disable impersonation
@@ -264,7 +266,7 @@ GET /projects?private_token=<your_access_token>&sudo=username
```
```shell
-curl --header "Private-Token: <your_access_token>" --header "Sudo: username" "https://gitlab.example.com/api/v4/projects"
+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,
@@ -275,7 +277,7 @@ GET /projects?private_token=<your_access_token>&sudo=23
```
```shell
-curl --header "Private-Token: <your_access_token>" --header "Sudo: 23" "https://gitlab.example.com/api/v4/projects"
+curl --header "PRIVATE-TOKEN: <your_access_token>" --header "Sudo: 23" "https://gitlab.example.com/api/v4/projects"
```
## Status codes
@@ -340,16 +342,19 @@ curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab
#### 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
-URL. Please use these links instead of generating your own URLs.
+[`Link` headers](https://www.w3.org/wiki/LinkHeader) are returned with each
+response. They have `rel` set to `prev`/`next`/`first`/`last` and contain the
+relevant URL. Be sure to use these links instead of generating your own URLs.
+
+NOTE: **Note:**
+For GitLab.com users, [some pagination headers may not be returned](../user/gitlab_com/index.md#pagination-response-headers).
In the cURL example below, we limit the output to 3 items per page (`per_page=3`)
and we request the second page (`page=2`) of [comments](notes.md) of the issue
-with ID `8` which belongs to the project with ID `8`:
+with ID `8` which belongs to the project with ID `9`:
```shell
-curl --head --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/8/issues/8/notes?per_page=3&page=2"
+curl --head --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/9/issues/8/notes?per_page=3&page=2"
```
The response will then be:
@@ -375,24 +380,19 @@ X-Total-Pages: 3
#### Other pagination headers
-Additional pagination headers are also sent back.
+GitLab also returns the following additional pagination headers:
-| Header | Description |
-| ------ | ----------- |
-| `X-Total` | The total number of items |
-| `X-Total-Pages` | The total number of pages |
-| `X-Per-Page` | The number of items per page |
+| Header | Description |
+| --------------- | --------------------------------------------- |
+| `X-Total` | The total number of items |
+| `X-Total-Pages` | The total number of pages |
+| `X-Per-Page` | The number of items per page |
| `X-Page` | The index of the current page (starting at 1) |
-| `X-Next-Page` | The index of the next page |
-| `X-Prev-Page` | The index of the previous page |
+| `X-Next-Page` | The index of the next page |
+| `X-Prev-Page` | The index of the previous page |
-CAUTION: **Caution:**
-For performance reasons since
-[GitLab 11.8](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/23931)
-and **behind the `api_kaminari_count_with_limit`
-[feature flag](../development/feature_flags/index.md)**, if the number of resources is
-more than 10,000, the `X-Total` and `X-Total-Pages` headers as well as the
-`rel="last"` `Link` are not present in the response headers.
+NOTE: **Note:**
+For GitLab.com users, [some pagination headers may not be returned](../user/gitlab_com/index.md#pagination-response-headers).
### Keyset-based pagination
@@ -639,7 +639,7 @@ follows:
## Unknown route
-When you try to access an API URL that does not exist you will receive 404 Not Found.
+When you try to access an API URL that does not exist, you will receive 404 Not Found.
```http
HTTP/1.1 404 Not Found