@@ -6,11 +6,15 @@ info: To determine the technical writer assigned to the Stage/Group associated w
# 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
...
...
@@ -19,21 +23,22 @@ For a list of the available resources and their endpoints, see
## 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
the `/Users` endpoint. The base URL is: `/api/scim/v2/groups/:group_path/Users/`.
[GitLab.com Silver and higher](https://about.gitlab.com/pricing/) 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 will
allow deprecation of controller-specific endpoints.
[GraphQL](graphql/index.md) is available in GitLab, which allows for the
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.
1. Callers of the API can request only what they need.
1. It is versioned by default.
- We avoid having to maintain two different APIs.
- Callers of the API can request only what they need.
- 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.
Although there were some patenting and licensing concerns with GraphQL, these
...
...
@@ -43,31 +48,31 @@ specification.
## Compatibility guidelines
The HTTP API is versioned using a single number, the current one being 4. This
number symbolizes the same as the major version number as described by
[SemVer](https://semver.org/). This mean that backward incompatible changes
will require this version number to change. However, the minor version is
not explicit. This allows for a stable API endpoint, but also means new
features can be added to the API in the same version number.
The HTTP API is versioned using a single number, (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
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
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:
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)
1.[Sudo](#sudo)
If authentication information is invalid or omitted, an error message will be
returned with status code `401`:
If authentication information is invalid or omitted, GitLab will return an error
message with a status code of `401`:
```json
{
...
...
@@ -113,8 +119,8 @@ returned with status code `401`:
### OAuth2 tokens
You can use an [OAuth2 token](oauth2.md) to authenticate with the API by passing it in either the
`access_token` parameter or the `Authorization` header.
You can use an [OAuth2 token](oauth2.md) to authenticate with the API by passing
it in either the `access_token` parameter or the `Authorization` header.
Example of using the OAuth2 token in a parameter:
...
...
@@ -132,22 +138,22 @@ 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.
You can use access tokens to authenticate with the API by passing it in either
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)
For more information, see the [users API](users.md#create-an-impersonation-token)
documentation.
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.
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.
#### 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)
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**
...
...
@@ -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)
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
NOTE: **Note:**
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.
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.
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
header name must be `Sudo`.
As an [administrator](../user/permissions.md), pass the `sudo` parameter either
by using query string or a header with an ID or username (case insensitive) of
the user you want to perform the operation as. If passed as a header, the header
name must be `Sudo`.
NOTE: **Note:**
Usernames are case insensitive.
If a non administrative access token is provided, an error message will
be returned with status code `403`:
If a non administrative access token is provided, GitLab returns an error
message with a status code of `403`:
```json
{
...
...
@@ -262,7 +268,7 @@ be returned with status code `403`:
```
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
{
...
...
@@ -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
returned with status code`404`:
returned with a status code of`404`:
```json
{
...
...
@@ -312,7 +318,7 @@ insight into what went wrong.
The following table gives an overview of how the API functions generally behave.
| Request type | Description |
| ------------ | ----------- |
|---------------|-------------|
| `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. |
| `GET` / `PUT` | Return `200 OK` if the resource is accessed or modified successfully. The (modified) result is returned as JSON. |
...
...
@@ -321,17 +327,17 @@ The following table gives an overview of how the API functions generally behave.
The following table shows the possible return codes for API requests.
| Return values | Description |
| ------------------------ | ----------- |
|--------------------------|-------------|
| `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. |
| `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. |
| `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. |
| `403 Forbidden` | The request is not allowed, e.g., 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. |
| `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. For example, an ID for a resource could not be found. |
| `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. |
| `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). |
...
...
@@ -339,26 +345,26 @@ The following table shows the possible return codes for API requests.
## 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.
- Keyset-based pagination. Added to selected endpoints but being
| `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
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
```
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 `Link` header was [added in GitLab 13.1](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/33714)
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.
The link to the next page contains an additional filter `id_after=42` that
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 don't expose additional pagination headers.
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.
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:
...
...
@@ -476,7 +489,9 @@ For example:
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:
...
...
@@ -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.
-`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:**
The `iid` is displayed in the web UI.
If a resource has the `iid` field and the `id` field, the `iid` field is usually used instead of `id` to fetch the resource.
If a resource has both 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`.
NOTE: **Note:**
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.
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.
## Data validation and error reporting
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
issue is not given
- An attribute did not pass the validation, e.g., the user bio is too long
- A required attribute of the API request is missing (for example, the title of
an issue isn't given).
- 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:
