@@ -6,11 +6,15 @@ info: To determine the technical writer assigned to the Stage/Group associated w
...
@@ -6,11 +6,15 @@ info: To determine the technical writer assigned to the Stage/Group associated w
# API Docs
# API Docs
Automate GitLab via a simple and powerful API.
Automate GitLab by using 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.
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 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.
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.
Contributions are welcome.
## Available API resources
## Available API resources
...
@@ -19,21 +23,22 @@ For a list of the available resources and their endpoints, see
...
@@ -19,21 +23,22 @@ For a list of the available resources and their endpoints, see
## SCIM **(SILVER ONLY)**
## SCIM **(SILVER ONLY)**
[GitLab.com Silver and above](https://about.gitlab.com/pricing/) provides an [SCIM API](scim.md) that implements [the RFC7644 protocol](https://tools.ietf.org/html/rfc7644) and provides
[GitLab.com Silver and higher](https://about.gitlab.com/pricing/) provides an
the `/Users` endpoint. The base URL is: `/api/scim/v2/groups/:group_path/Users/`.
[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
## Road to GraphQL
[GraphQL](graphql/index.md) is available in GitLab, which will
[GraphQL](graphql/index.md) is available in GitLab, which allows for the
allow deprecation of controller-specific endpoints.
deprecation of controller-specific endpoints.
GraphQL has a number of benefits:
GraphQL has several benefits, including:
1. We avoid having to maintain two different APIs.
- We avoid having to maintain two different APIs.
1. Callers of the API can request only what they need.
- Callers of the API can request only what they need.
1. It is versioned by default.
- It's versioned by default.
It will co-exist with the current v4 REST API. If we have a v5 API, this should
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.
be a compatibility layer on top of GraphQL.
Although there were some patenting and licensing concerns with GraphQL, these
Although there were some patenting and licensing concerns with GraphQL, these
...
@@ -43,31 +48,31 @@ specification.
...
@@ -43,31 +48,31 @@ specification.
## Compatibility guidelines
## Compatibility guidelines
The HTTP API is versioned using a single number, the current one being 4. This
The HTTP API is versioned using a single number, (currently _4_). This number
number symbolizes the same as the major version number as described by
symbolizes the major version number, as described by [SemVer](https://semver.org/).
[SemVer](https://semver.org/). This mean that backward incompatible changes
Because of this, backwards-incompatible changes require this version number to
will require this version number to change. However, the minor version is
change. However, the minor version isn't explicit, allowing for a stable API
not explicit. This allows for a stable API endpoint, but also means new
endpoint. This also means that new features can be added to the API in the same
features can be added to the API in the same version number.
version number.
New features and bug fixes are released in tandem with a new GitLab, and apart
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
from incidental patch and security releases, are released on the 22nd of each
to build applications or scripts that do so, the following options are available:
For admins who want to authenticate with the API as a specific user, or who want to build applications or scripts that do so, two options are available:
-[Impersonation tokens](#impersonation-tokens)
-[Sudo](#sudo)
1.[Impersonation tokens](#impersonation-tokens)
If authentication information is invalid or omitted, GitLab will return an error
1.[Sudo](#sudo)
message with a status code of `401`:
If authentication information is invalid or omitted, an error message will be
returned with status code `401`:
```json
```json
{
{
...
@@ -113,8 +119,8 @@ returned with status code `401`:
...
@@ -113,8 +119,8 @@ returned with status code `401`:
### OAuth2 tokens
### OAuth2 tokens
You can use an [OAuth2 token](oauth2.md) to authenticate with the API by passing it in either the
You can use an [OAuth2 token](oauth2.md) to authenticate with the API by passing
`access_token` parameter or the `Authorization` header.
it in either the `access_token` parameter or the `Authorization` header.
Example of using the OAuth2 token in a parameter:
Example of using the OAuth2 token in a parameter:
...
@@ -132,22 +138,22 @@ Read more about [GitLab as an OAuth2 provider](oauth2.md).
...
@@ -132,22 +138,22 @@ Read more about [GitLab as an OAuth2 provider](oauth2.md).
### Personal/project access tokens
### Personal/project access tokens
Access tokens can be used to authenticate with the API by passing it in either the `private_token` parameter
You can use access tokens to authenticate with the API by passing it in either
or the `PRIVATE-TOKEN` header.
the `private_token` parameter or the `PRIVATE-TOKEN` header.
Example of using the personal/project access token in a parameter:
Example of using the personal or project access token in a parameter:
-[Container Registry](../user/packages/container_registry/index.md)(`$CI_REGISTRY_PASSWORD` is actually `$CI_JOB_TOKEN`, but this may change in the future)
Impersonation tokens are used exactly like regular personal access tokens, and can be passed in either the
Impersonation tokens are used exactly like regular personal access tokens, and
`private_token` parameter or the `PRIVATE-TOKEN` header.
can be passed in either the `private_token` parameter or the `PRIVATE-TOKEN`
header.
#### Disable impersonation
#### Disable impersonation
...
@@ -220,7 +229,8 @@ By default, impersonation is enabled. To disable impersonation:
...
@@ -220,7 +229,8 @@ By default, impersonation is enabled. To disable impersonation:
1. Save the file and [reconfigure](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure)
1. Save the file and [reconfigure](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure)
GitLab for the changes to take effect.
GitLab for the changes to take effect.
To re-enable impersonation, remove this configuration and reconfigure GitLab.
To re-enable impersonation, remove this configuration, and then reconfigure
GitLab.
**For installations from source**
**For installations from source**
...
@@ -234,26 +244,22 @@ To re-enable impersonation, remove this configuration and reconfigure GitLab.
...
@@ -234,26 +244,22 @@ To re-enable impersonation, remove this configuration and reconfigure GitLab.
1. Save the file and [restart](../administration/restart_gitlab.md#installations-from-source)
1. Save the file and [restart](../administration/restart_gitlab.md#installations-from-source)
GitLab for the changes to take effect.
GitLab for the changes to take effect.
To re-enable impersonation, remove this configuration and restart GitLab.
To re-enable impersonation, remove this configuration, and then restart GitLab.
### Sudo
### Sudo
NOTE: **Note:**
Only available to [administrators](../user/permissions.md).
All API requests support performing an API call as if you were another user,
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.
provided you're authenticated as an administrator with an OAuth or personal
The API requests are executed with the permissions of the impersonated user.
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
As an [administrator](../user/permissions.md), pass the `sudo` parameter either
the user you want to perform the operation as. If passed as a header, the
by using query string or a header with an ID or username (case insensitive) of
header name must be `Sudo`.
the user you want to perform the operation as. If passed as a header, the header
name must be `Sudo`.
NOTE: **Note:**
If a non administrative access token is provided, GitLab returns an error
Usernames are case insensitive.
message with a status code of `403`:
If a non administrative access token is provided, an error message will
be returned with status code `403`:
```json
```json
{
{
...
@@ -262,7 +268,7 @@ be returned with status code `403`:
...
@@ -262,7 +268,7 @@ be returned with status code `403`:
```
```
If an access token without the `sudo` scope is provided, an error message will
If an access token without the `sudo` scope is provided, an error message will
be returned with status code`403`:
be returned with a status code of`403`:
```json
```json
{
{
...
@@ -273,7 +279,7 @@ be returned with status code `403`:
...
@@ -273,7 +279,7 @@ be returned with status code `403`:
```
```
If the sudo user ID or username cannot be found, an error message will be
If the sudo user ID or username cannot be found, an error message will be
returned with status code`404`:
returned with a status code of`404`:
```json
```json
{
{
...
@@ -311,27 +317,27 @@ insight into what went wrong.
...
@@ -311,27 +317,27 @@ insight into what went wrong.
The following table gives an overview of how the API functions generally behave.
The following table gives an overview of how the API functions generally behave.
| Request type | Description |
| Request type | Description |
| ------------ | ----------- |
|---------------|-------------|
| `GET` | Access one or more resources and return the result as JSON. |
| `GET`| Access one or more resources and return the result as JSON. |
| `POST` | Return `201 Created` if the resource is successfully created and return the newly created resource as JSON. |
| `POST`| Return `201 Created` if the resource is successfully created and return the newly created resource as JSON. |
| `GET` / `PUT` | Return `200 OK` if the resource is accessed or modified successfully. The (modified) result is returned as JSON. |
| `GET` / `PUT` | Return `200 OK` if the resource is accessed or modified successfully. The (modified) result is returned as JSON. |
| `DELETE` | Returns `204 No Content` if the resource was deleted successfully. |
| `DELETE`| Returns `204 No Content` if the resource was deleted successfully. |
The following table shows the possible return codes for API requests.
The following table shows the possible return codes for API requests.
| Return values | Description |
| Return values | Description |
| ------------------------ | ----------- |
|--------------------------|-------------|
| `200 OK` | The `GET`, `PUT` or `DELETE` request was successful, the resource(s) itself is returned as JSON. |
| `200 OK` | The `GET`, `PUT` or `DELETE` request was successful, the resource(s) itself is returned as JSON. |
| `204 No Content` | The server has successfully fulfilled the request and that there is no additional content to send in the response payload body. |
| `204 No Content` | The server has successfully fulfilled the request and that there is no additional content to send in the response payload body. |
| `201 Created` | The `POST` request was successful and the resource is returned as JSON. |
| `201 Created` | The `POST` request was successful and the resource is returned as JSON. |
| `304 Not Modified` | Indicates that the resource has not been modified since the last request. |
| `304 Not Modified` | Indicates that the resource has not been modified since the last request. |
| `400 Bad Request` | A required attribute of the API request is missing, e.g., the title of an issue is not given. |
| `400 Bad Request` | A required attribute of the API request is missing, e.g., the title of an issue is not given. |
| `401 Unauthorized` | The user is not authenticated, a valid [user token](#authentication) is necessary. |
| `401 Unauthorized` | The user is not authenticated, a valid [user token](#authentication) is necessary. |
| `403 Forbidden` | The request is not allowed, e.g., the user is not allowed to delete a project. |
| `403 Forbidden` | The request is not allowed. For example, the user is not allowed to delete a project. |
| `404 Not Found` | A resource could not be accessed, e.g., an ID for a resource could not be found. |
| `404 Not Found` | A resource could not be accessed. For example, an ID for a resource could not be found. |
| `405 Method Not Allowed` | The request is not supported. |
| `405 Method Not Allowed` | The request is not supported. |
| `409 Conflict` | A conflicting resource already exists, e.g., creating a project with a name that already exists. |
| `409 Conflict` | A conflicting resource already exists. For example, creating a project with a name that already exists. |
| `412` | Indicates the request was denied. May happen if the `If-Unmodified-Since` header is provided when trying to delete a resource, which was modified in between. |
| `412` | Indicates the request was denied. May happen if the `If-Unmodified-Since` header is provided when trying to delete a resource, which was modified in between. |
| `422 Unprocessable` | The entity could not be processed. |
| `422 Unprocessable` | The entity could not be processed. |
| `429 Too Many Requests` | The user exceeded the [application rate limits](../administration/instance_limits.md#rate-limits). |
| `429 Too Many Requests` | The user exceeded the [application rate limits](../administration/instance_limits.md#rate-limits). |
...
@@ -339,26 +345,26 @@ The following table shows the possible return codes for API requests.
...
@@ -339,26 +345,26 @@ The following table shows the possible return codes for API requests.
## Pagination
## Pagination
We support two kinds of pagination methods:
GitLab supports the following pagination methods:
- Offset-based pagination. This is the default method and available on all endpoints.
- Offset-based pagination. This is the default method and available on all endpoints.
- Keyset-based pagination. Added to selected endpoints but being
- Keyset-based pagination. Added to selected endpoints but being
| `per_page` | Number of items to list per page (default: `20`, max: `100`) |
| `per_page` | Number of items to list per page (default: `20`, max: `100`). |
In the example below, we list 50 [projects](projects.md) per page, ordered by `id` ascending.
In the following example, we list 50 [projects](projects.md) per page, ordered
by `id` ascending.
```shell
```shell
curl --request GET --header"PRIVATE-TOKEN: <your_access_token>""https://gitlab.example.com/api/v4/projects?pagination=keyset&per_page=50&order_by=id&sort=asc"
curl --request GET --header"PRIVATE-TOKEN: <your_access_token>""https://gitlab.example.com/api/v4/projects?pagination=keyset&per_page=50&order_by=id&sort=asc"
...
@@ -448,27 +454,34 @@ Status: 200 OK
...
@@ -448,27 +454,34 @@ Status: 200 OK
```
```
CAUTION: **Deprecation:**
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
The `Link` header was [added in GitLab 13.1](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/33714)
[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.
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.
The link to the next page contains an additional filter `id_after=42` that
Note the type of filter depends on the `order_by` option used and we may have more than one additional filter.
excludes already-retrieved records. 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 `Link` 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 recommend using only the given link to retrieve the next page instead of
we don't expose additional pagination headers.
building your own URL. Apart from the headers shown, we don't expose additional
pagination headers.
Keyset-based pagination is only supported for selected resources and ordering options:
Keyset-based pagination is supported only for selected resources and ordering
If an endpoint has path parameters, the documentation shows them with a preceding colon.
If an endpoint has path parameters, the documentation displays them with a
preceding colon.
For example:
For example:
...
@@ -476,7 +489,9 @@ For example:
...
@@ -476,7 +489,9 @@ For example:
DELETE /projects/:id/share/:group_id
DELETE /projects/:id/share/:group_id
```
```
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 `:` should not be included.
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 call for a project with ID `5` and a group ID of `17` is then:
...
@@ -484,11 +499,10 @@ The resulting cURL call for a project with ID `5` and a group ID of `17` is then
...
@@ -484,11 +499,10 @@ The resulting cURL call for a project with ID `5` and a group ID of `17` is then
Some resources have two similarly-named fields. For example, [issues](issues.md), [merge requests](merge_requests.md), and [project milestones](merge_requests.md). The fields are:
Some resources have two similarly-named fields. For example, [issues](issues.md),
[merge requests](merge_requests.md), and [project milestones](merge_requests.md).
The fields are:
-`id`: ID that is unique across all projects.
-`id`: ID that is unique across all projects.
-`iid`: additional, internal ID that is unique in the scope of a single project.
-`iid`: Additional, internal ID (displayed in the web UI) that's unique in the
scope of a single project.
NOTE: **Note:**
If a resource has both the `iid` field and the `id` field, the `iid` field is
The `iid` is displayed in the web UI.
usually used instead of `id` to fetch the resource.
If a resource has the `iid` field and the `id` field, the `iid` field is 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:
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`
- 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`.
- An invalid API call to retrieve the issue is `GET /projects/42/issues/46`.
NOTE: **Note:**
Not all resources with the `iid` field are fetched by `iid`. For guidance
Not all resources with the `iid` field are fetched by `iid`. For guidance on which field to use, see the documentation for the specific resource.
regarding which field to use, see the documentation for the specific resource.
## Data validation and error reporting
## Data validation and error reporting
When working with the API you may encounter validation errors, in which case
When working with the API you may encounter validation errors, in which case
the API will answer with an HTTP `400` status.
the API returns an HTTP `400` error.
Such errors appear in two cases:
Such errors appear in the following cases:
- A required attribute of the API request is missing, e.g., the title of an
- A required attribute of the API request is missing (for example, the title of
issue is not given
an issue isn't given).
- An attribute did not pass the validation, e.g., the user bio is too long
- An attribute did not pass the validation (for example, the user bio is too
long).
When an attribute is missing, you will get something like:
When an attribute is missing, you will get something like:
