diff options
Diffstat (limited to 'doc/api/rest')
-rw-r--r-- | doc/api/rest/deprecations.md | 112 | ||||
-rw-r--r-- | doc/api/rest/index.md | 122 |
2 files changed, 179 insertions, 55 deletions
diff --git a/doc/api/rest/deprecations.md b/doc/api/rest/deprecations.md new file mode 100644 index 00000000000..db9b590606f --- /dev/null +++ b/doc/api/rest/deprecations.md @@ -0,0 +1,112 @@ +--- +stage: Manage +group: Import and Integrate +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# REST API deprecations and removals + +The following API changes will occur when the v4 API is removed. + +The date of this change is unknown. +For details, see [issue 216456](https://gitlab.com/gitlab-org/gitlab/-/issues/216456) +and [issue 387485](https://gitlab.com/gitlab-org/gitlab/-/issues/387485). + +## `geo_nodes` API endpoints + +Breaking change. [Related issue](https://gitlab.com/gitlab-org/gitlab/-/issues/369140). + +The [`geo_nodes` API endpoints](../geo_nodes.md) are deprecated and are replaced by [`geo_sites`](../geo_sites.md). +It is a part of the global change on [how to refer to Geo deployments](../../administration/geo/glossary.md). +Nodes are renamed to sites across the application. The functionality of both endpoints remains the same. + +## `merged_by` API field + +Breaking change. [Related issue](https://gitlab.com/gitlab-org/gitlab/-/issues/350534). + +The `merged_by` field in the [merge request API](../merge_requests.md#list-merge-requests) +has been deprecated in favor of the `merge_user` field which more correctly identifies who merged a merge request when +performing actions (merge when pipeline succeeds, add to merge train) other than a simple merge. + +API users are encouraged to use the new `merge_user` field instead. The `merged_by` field will be removed in v5 of the GitLab REST API. + +## `merge_status` API field + +Breaking change. [Related issue](https://gitlab.com/gitlab-org/gitlab/-/issues/382032). + +The `merge_status` field in the [merge request API](../merge_requests.md#merge-status) +has been deprecated in favor of the `detailed_merge_status` field which more correctly identifies +all of the potential statuses that a merge request can be in. API users are encouraged to use the +new `detailed_merge_status` field instead. The `merge_status` field will be removed in v5 of the GitLab REST API. + +### Null value for `private_profile` attribute in User API + +Breaking change. [Related issue](https://gitlab.com/gitlab-org/gitlab/-/issues/387005). + +When creating and updating users through the API, `null` was a valid value for the `private_profile` attribute, which would internally be converted to the default value. In v5 of the GitLab REST API, `null` will no longer be a valid value for this parameter, and the response will be a 400 if used. After this change, the only valid values will be `true` and `false`. + +## Single merge request changes API endpoint + +Breaking change. [Related issue](https://gitlab.com/gitlab-org/gitlab/-/issues/322117). + +The endpoint to get +[changes from a single merge request](../merge_requests.md#get-single-merge-request-changes) +has been deprecated in favor the +[list merge request diffs](../merge_requests.md#list-merge-request-diffs) endpoint. +API users are encouraged to switch to the new diffs endpoint instead. + +The `changes from a single merge request` endpoint will be removed in v5 of the GitLab REST API. + +## Managed Licenses API endpoint + +Breaking change. [Related issue](https://gitlab.com/gitlab-org/gitlab/-/issues/397067). + +The endpoint to get +[all managed licenses for a given project](../managed_licenses.md) +has been deprecated in favor the +[License Approval policy](../../user/compliance/license_approval_policies.md) feature. +Users who wish to continue to enforce approvals based on detected licenses are encouraged to create a new [License Approval policy](../../user/compliance/license_approval_policies.md) instead. + +The `managed licenses` endpoint will be removed in v5 of the GitLab REST API. + +## Approvers and Approver Group fields in Merge Request Approval API + +Breaking change. [Related issue](https://gitlab.com/gitlab-org/gitlab/-/issues/353097). + +The endpoint to get the configuration of approvals for a project returns +empty arrays for `approvers` and `approval_groups`. +These fields were deprecated in favor of the endpoint to +[get project-level rules](../merge_request_approvals.md#get-project-level-rules) +for a merge request. API users are encouraged to switch to this endpoint instead. + +These fields will be removed from the `get configuration` endpoint in v5 of the GitLab REST API. + +## Runner usage of `active` replaced by `paused` + +Breaking change. [Related issue](https://gitlab.com/gitlab-org/gitlab/-/issues/351109). + +Occurrences of the `active` identifier in the GitLab Runner GraphQL API endpoints will be +renamed to `paused` in GitLab 16.0. + +- In v4 of the REST API, starting in GitLab 14.8, you can use the `paused` property in place of `active` +- In v5 of the REST API, this change will affect endpoints taking or returning `active` property, such as: + - `GET /runners` + - `GET /runners/all` + - `GET /runners/:id` / `PUT /runners/:id` + - `PUT --form "active=false" /runners/:runner_id` + - `GET /projects/:id/runners` / `POST /projects/:id/runners` + - `GET /groups/:id/runners` + +The 16.0 release of GitLab Runner will start using the `paused` property when registering runners. + +## Runner status will not return `paused` + +Breaking change. [Related issue](https://gitlab.com/gitlab-org/gitlab/-/issues/344648). + +In a future v5 of the REST API, the endpoints for GitLab Runner will not return `paused` or `active`. + +A runner's status will only relate to runner contact status, such as: +`online`, `offline`, or `not_connected`. Status `paused` or `active` will no longer appear. + +When checking if a runner is `paused`, API users are advised to check the boolean attribute +`paused` to be `true` instead. When checking if a runner is `active`, check if `paused` is `false`. diff --git a/doc/api/rest/index.md b/doc/api/rest/index.md index 57d13f2a54f..0bee7168cfb 100644 --- a/doc/api/rest/index.md +++ b/doc/api/rest/index.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Integrations +group: Import and Integrate info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- @@ -12,7 +12,7 @@ developers who are more comfortable with traditional API architecture. ## Compatibility guidelines -The HTTP API is versioned with a single number, which is currently `4`. This number +The HTTP API is versioned with a single number, which is `4`. This number symbolizes the major version number, as described by [SemVer](https://semver.org/). Because of this, backward-incompatible changes require this version number to change. @@ -83,9 +83,9 @@ authentication isn't provided. When authentication is not required, the document for each endpoint specifies this. For example, the [`/projects/:id` endpoint](../projects.md#get-single-project) does not require authentication. -There are several ways you can authenticate with the GitLab API: +You can authenticate with the GitLab API in several ways: -- [OAuth2 tokens](#oauth2-tokens) +- [OAuth 2.0 tokens](#oauth-20-tokens) - [Personal access tokens](../../user/profile/personal_access_tokens.md) - [Project access tokens](../../user/project/settings/project_access_tokens.md) - [Group access tokens](../../user/group/settings/group_access_tokens.md) @@ -94,8 +94,8 @@ There are several ways you can authenticate with the GitLab API: Project access tokens are supported by: -- Self-managed GitLab Free and higher. -- GitLab SaaS Premium and higher. +- Self-managed GitLab: Free, Premium, and Ultimate. +- GitLab SaaS: Premium and Ultimate. If you are an administrator, you or your application can authenticate as a specific user. To do so, use: @@ -116,30 +116,30 @@ NOTE: Deploy tokens can't be used with the GitLab public API. For details, see [Deploy Tokens](../../user/project/deploy_tokens/index.md). -### OAuth2 tokens +### OAuth 2.0 tokens -You can use an [OAuth2 token](../oauth2.md) to authenticate with the API by passing +You can use an [OAuth 2.0 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: +Example of using the OAuth 2.0 token in a parameter: ```shell curl "https://gitlab.example.com/api/v4/projects?access_token=OAUTH-TOKEN" ``` -Example of using the OAuth2 token in a header: +Example of using the OAuth 2.0 token in a header: ```shell curl --header "Authorization: Bearer OAUTH-TOKEN" "https://gitlab.example.com/api/v4/projects" ``` -Read more about [GitLab as an OAuth2 provider](../oauth2.md). +Read more about [GitLab as an OAuth 2.0 provider](../oauth2.md). NOTE: -We recommend OAuth access tokens have an expiration. You can use the `refresh_token` parameter +You should give OAuth access tokens an expiration. You can use the `refresh_token` parameter to refresh tokens. Integrations may need to be updated to use refresh tokens prior to expiration, which is based on the [`expires_in`](https://datatracker.ietf.org/doc/html/rfc6749#appendix-A.14) -property in the token endpoint response. See [OAuth2 token](../oauth2.md) documentation +property in the token endpoint response. See [OAuth 2.0 token](../oauth2.md) documentation for examples requesting a new access token using a refresh token. A default refresh setting of two hours is tracked in [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/336598). @@ -299,52 +299,52 @@ 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. | +| 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. | | `DELETE` | Returns `204 No Content` if the resource was deleted successfully or `202 Accepted` if the resource is scheduled to be deleted. | The following table shows the possible return codes for API requests. -| Return values | Description | -|--------------------------|-------------| -| `200 OK` | The `GET`, `PUT` or `DELETE` request was successful, and the resource itself is returned as JSON. | -| `202 Accepted` | The `GET`, `PUT` or `DELETE` request was successful, and the resource is scheduled for processing. | -| `204 No Content` | The server has successfully fulfilled the request, and 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` | The resource hasn't been modified since the last request. | -| `400 Bad Request` | A required attribute of the API request is missing. For example, the title of an issue is not given. | -| `401 Unauthorized` | The user isn't authenticated. A valid [user token](#authentication) is necessary. | -| `403 Forbidden` | The request isn't allowed. For example, the user isn't allowed to delete a project. | -| `404 Not Found` | A resource couldn't be accessed. For example, an ID for a resource couldn't be found. | -| `405 Method Not Allowed` | The request isn't supported. | -| `409 Conflict` | A conflicting resource already exists. For example, creating a project with a name that already exists. | -| `412` | The request was denied. This can happen if the `If-Unmodified-Since` header is provided when trying to delete a resource, which was modified in between. | -| `422 Unprocessable` | The entity couldn't be processed. | -| `429 Too Many Requests` | The user exceeded the [application rate limits](../../administration/instance_limits.md#rate-limits). | -| `500 Server Error` | While handling the request, something went wrong on the server. | +| Return values | Description | +|:--------------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------| +| `200 OK` | The `GET`, `PUT` or `DELETE` request was successful, and the resource itself is returned as JSON. | +| `201 Created` | The `POST` request was successful, and the resource is returned as JSON. | +| `202 Accepted` | The `GET`, `PUT` or `DELETE` request was successful, and the resource is scheduled for processing. | +| `204 No Content` | The server has successfully fulfilled the request, and there is no additional content to send in the response payload body. | +| `304 Not Modified` | The resource hasn't been modified since the last request. | +| `400 Bad Request` | A required attribute of the API request is missing. For example, the title of an issue is not given. | +| `401 Unauthorized` | The user isn't authenticated. A valid [user token](#authentication) is necessary. | +| `403 Forbidden` | The request isn't allowed. For example, the user isn't allowed to delete a project. | +| `404 Not Found` | A resource couldn't be accessed. For example, an ID for a resource couldn't be found, or the user isn't authorized to access the resource. | +| `405 Method Not Allowed` | The request isn't supported. | +| `409 Conflict` | A conflicting resource already exists. For example, creating a project with a name that already exists. | +| `412 Precondition Failed` | The request was denied. This can happen if the `If-Unmodified-Since` header is provided when trying to delete a resource, which was modified in between. | +| `422 Unprocessable` | The entity couldn't be processed. | +| `429 Too Many Requests` | The user exceeded the [application rate limits](../../administration/instance_limits.md#rate-limits). | +| `500 Server Error` | While handling the request, something went wrong on the server. | ## Pagination GitLab supports the following pagination methods: -- Offset-based pagination. This is the default method and is available on all endpoints. +- Offset-based pagination. The default method and available on all endpoints. - Keyset-based pagination. Added to selected endpoints but being [progressively rolled out](https://gitlab.com/groups/gitlab-org/-/epics/2039). -For large collections, for performance reasons we recommend keyset pagination -(when available) instead of offset pagination. +For large collections, you should use keyset pagination +(when available) instead of offset pagination, for performance reasons. ### Offset-based pagination Sometimes, the returned result spans many pages. When listing resources, you can pass the following parameters: -| Parameter | Description | -|------------|-------------| -| `page` | Page number (default: `1`). | +| Parameter | Description | +|:-----------|:--------------------------------------------------------------| +| `page` | Page number (default: `1`). | | `per_page` | Number of items to list per page (default: `20`, max: `100`). | In the following example, we list 50 [namespaces](../namespaces.md) per page: @@ -397,14 +397,14 @@ x-total-pages: 3 GitLab also returns the following additional pagination headers: -| Header | Description | -|-----------------|-------------| -| `x-next-page` | The index of the next page. | +| Header | Description | +|:----------------|:-----------------------------------------------| +| `x-next-page` | The index of the next page. | | `x-page` | The index of the current page (starting at 1). | -| `x-per-page` | The number of items per page. | -| `x-prev-page` | The index of the previous page. | -| `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-prev-page` | The index of the previous page. | +| `x-total` | The total number of items. | +| `x-total-pages` | The total number of pages. | For GitLab.com users, [some pagination headers may not be returned](../../user/gitlab_com/index.md#pagination-response-headers). @@ -476,19 +476,23 @@ When the end of the collection is 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 +You should use 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. +#### Supported resources + Keyset-based pagination is supported only for selected resources and ordering options: -| Resource | Options | Availability | -|:---------------------------------------------------------|:---------------------------------|:-------------------------------------------------------------------------------------------------------------| -| [Projects](../projects.md) | `order_by=id` only | Authenticated and unauthenticated users | -| [Groups](../groups.md) | `order_by=name`, `sort=asc` only | Unauthenticated users only | -| [Group audit events](../audit_events.md#group-audit-events) | `order_by=id`, `sort=desc` only | Authenticated users only ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/333968) in GitLab 15.2) | -| [Jobs](../jobs.md) | `order_by=id`, `sort=desc` only | Authenticated users only ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/362172) in GitLab 15.9) | +| Resource | Options | Availability | +|:------------------------------------------------------------------|:---------------------------------|:--------------------------------------------------------------------------------------------------------------| +| [Group audit events](../audit_events.md#group-audit-events) | `order_by=id`, `sort=desc` only | Authenticated users only ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/333968) in GitLab 15.2) | +| [Groups](../groups.md) | `order_by=name`, `sort=asc` only | Unauthenticated users only | +| [Instance audit events](../audit_events.md#instance-audit-events) | `order_by=id`, `sort=desc` only | Authenticated users only ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/367528) in GitLab 15.11) | +| [Jobs](../jobs.md) | `order_by=id`, `sort=desc` only | Authenticated users only ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/362172) in GitLab 15.9) | +| [Project audit events](../audit_events.md#project-audit-events) | `order_by=id`, `sort=desc` only | Authenticated users only ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/367528) in GitLab 15.10) | +| [Projects](../projects.md) | `order_by=id` only | Authenticated and unauthenticated users | ### Pagination response headers @@ -642,6 +646,14 @@ For example, suppose a project with `id: 42` has an issue with `id: 46` and 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. +## `null` vs `false` + +In API responses, some boolean fields can have `null` values. +A `null` boolean has no default value and is neither `true` nor `false`. +GitLab treats `null` values in boolean fields the same as `false`. + +In boolean arguments, you should only set `true` or `false` values (not `null`). + ## Data validation and error reporting When working with the API you may encounter validation errors, in which case |