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.md174
1 files changed, 100 insertions, 74 deletions
diff --git a/doc/api/README.md b/doc/api/README.md
index 35eeb5ae99b..1a914fb1dbe 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,34 +108,34 @@ 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)
- [Project access tokens](../user/project/settings/project_access_tokens.md)
- [Session cookie](#session-cookie)
-- [GitLab CI/CD job token](#gitlab-ci-job-token) **(Specific endpoints only)**
+- [GitLab CI/CD job token](#gitlab-cicd-job-token) **(Specific endpoints only)**
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,37 +193,65 @@ 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 job token
+### GitLab CI/CD job 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:
+When a pipeline job is about to run, GitLab generates a unique token and injects it as the
+[`CI_JOB_TOKEN` predefined variable](../ci/variables/predefined_variables.md).
+
+You can use a GitLab CI/CD job token to authenticate with specific API endpoints:
- Packages:
- - [Package Registry](../user/packages/package_registry/index.md)
+ - [Package Registry](../user/packages/package_registry/index.md). To push to the
+ Package Registry, you can use [deploy tokens](../user/project/deploy_tokens/index.md).
- [Container Registry](../user/packages/container_registry/index.md)
- (`$CI_REGISTRY_PASSWORD` is `$CI_JOB_TOKEN`)
-- [Get job artifacts](job_artifacts.md#get-job-artifacts)
-- [Get job token's job](jobs.md#get-job-tokens-job)
-- [Pipeline triggers](pipeline_triggers.md) (using the `token=` parameter)
-- [Release creation](releases/index.md#create-a-release)
-- [Terraform plan](../user/infrastructure/index.md)
+ (the `$CI_REGISTRY_PASSWORD` is `$CI_JOB_TOKEN`).
+- [Get job artifacts](job_artifacts.md#get-job-artifacts).
+- [Get job token's job](jobs.md#get-job-tokens-job).
+- [Pipeline triggers](pipeline_triggers.md), using the `token=` parameter.
+- [Release creation](releases/index.md#create-a-release).
+- [Terraform plan](../user/infrastructure/index.md).
+
+The token has the same permissions to access the API as the user that triggers the
+pipeline. Therefore, this user must be assigned to [a role that has the required privileges](../user/permissions.md).
-The token is valid as long as the job is running.
+The token is valid only while the pipeline job runs. After the job finishes, you can't
+use the token anymore.
+
+A job token can access a project's resources without any configuration, but it might
+give extra permissions that aren't necessary. There is [a proposal](https://gitlab.com/groups/gitlab-org/-/epics/3559)
+to redesign the feature for more strategic control of the access permissions.
+
+#### GitLab CI/CD job token security
+
+To make sure that this token doesn't leak, GitLab:
+
+- Masks the job token in job logs.
+- Grants permissions to the job token only when the job is running.
+
+To make sure that this token doesn't leak, you should also configure
+your [runners](../ci/runners/README.md) to be secure. Avoid:
+
+- Using Docker's `privileged` mode if the machines are re-used.
+- Using the [`shell` executor](https://docs.gitlab.com/runner/executors/shell.html) when jobs
+ run on the same machine.
+
+If you have an insecure GitLab Runner configuration, you increase the risk that someone
+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.
@@ -270,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.
@@ -309,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
@@ -320,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
@@ -334,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.
@@ -515,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"
@@ -528,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`:
@@ -578,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`
@@ -636,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.
@@ -734,7 +760,7 @@ The correct encoding for the query parameter would be:
## Clients
There are many unofficial GitLab API Clients for most of the popular programming
-languages. For a complete list, visit the [GitLab website](https://about.gitlab.com/partners/#api-clients).
+languages. For a complete list, visit the [GitLab website](https://about.gitlab.com/partners/technology-partners/#api-clients).
## Rate limits