Documenting REST API resources

REST API resources are documented in Markdown under /doc/api. Each resource has its own Markdown file, which is linked from api_resources.md.

When modifying the Markdown or API code, also update the corresponding OpenAPI definition, by running bin/rake gitlab:openapi:generate. To check if the OpenAPI definition needs to be updated, you can run bin/rake gitlab:openapi:check_docs. This is also checked by the openapi-doc-check CI/CD job that runs for commits that modify API code or documentation.

The Markdown topic for an API resource must include:

• A block that includes the HTTP method (like GET, PUT, DELETE) followed by the request path. Always start the path with a /. For example:

  GET /api/v4/projects/:id/repository/branches

• A detailed description of the attributes.

• A detailed description of the response body.

• A cURL example.

• A response body example (in JSON format).

After a new API documentation page is added, add an entry in the global navigation.

API topic template

Use the following template to help you get started. Be sure to list any required attributes first in the table.

## API name

{{< history >}}

- History note.

{{< /history >}}

Use this API to ...

### Operation title

{{< history >}}

- History note.

{{< /history >}}

Description of the operation.

```plaintext
METHOD /api/v4/endpoint
```

Supported attributes:

| Attribute                | Type     | Required | Description           |
|--------------------------|----------|----------|-----------------------|
| `attribute`              | datatype | Yes      | Detailed description. |
| `attribute`              | datatype | No       | Detailed description. |
| `attribute`              | datatype | No       | Detailed description. |
| `attribute`              | datatype | No       | Detailed description. |

If successful, returns [`<status_code>`](rest/troubleshooting.md#status-codes) and the following
response attributes:

| Attribute                | Type     | Description           |
|--------------------------|----------|-----------------------|
| `attribute`              | datatype | Detailed description. |
| `attribute`              | datatype | Detailed description. |

Example request:

```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/endpoint?parameters"
```

Example response:

```json
[
  {
  }
]
```

History

Add history to describe new or updated API calls.

To add history for an individual attribute, include it in the history for the section. For example:

### Edit a widget

{{< history >}}

 - `widget_message` [introduced](https://link-to-issue) in GitLab 14.3.

{{< /history >}}

If the API or attribute is deployed behind a feature flag, include the feature flag information in the history.

Deprecations

To document the deprecation of an API endpoint, follow the steps to deprecate a page or topic.

To deprecate an attribute:

1. Add a history note.

   {{< history >}}
   
   - `widget_name` [deprecated](https://link-to-issue) in GitLab 14.7.
   
   {{< /history >}}

2. Add inline deprecation text to the description.

   | Attribute     | Type   | Required | Description |
   |---------------|--------|----------|-------------|
   | `widget_name` | string | No       | [Deprecated](https://link-to-issue) in GitLab 14.7. Use `widget_id` instead. The name of the widget. |

To widely announce a deprecation, update the REST API deprecations page.

API introduction

Each API is made of one or more operations. At the start of the topic, include information that applies to all operations in the API, and a short description of the related features.

For consistency, try to start the introduction with: Use this API to {verb} + [{feature}](link/to/UI/docs). This allows us to direct users to related documentation that might include more context.

For example:

• Use this API to manage [Git branches](path/to/file).
• Use this API to interact with the [Maven package manager client](path/to/file).
• Use this API to interact with namespaces, a special resource category used to organize users and groups. For more information, see [namespaces](path/to/file).

Operation descriptions

Each operation should include a short description that explains its use, and highlights any important information. If possible, write the first sentence to broadly repeat the title of the operation. For example:

• List all project access tokens -> Lists all project access tokens.
• Delete an SSH key -> Deletes an SSH key from your user account.
• Get details on an enterprise user -> Gets details on a specified enterprise user.

Attribute descriptions

You must document the attributes in an operation. When creating the table and attribute descriptions:

• Use the following column names for attribute tables.
• List any path attributes first, then any required attributes, then sort alphabetically.
• Place attributes name in code blocks using backticks (`).
• Document any tier or offering information specific to an attribute in the description.
  • If an attribute is available for Premium, mention that it’s also available for Ultimate.
  • Combine this tier and offering information when possible. For example: GitLab Self-Managed, Premium and Ultimate only.

| Attribute                    | Type          | Required | Description                                         |
|------------------------------|---------------|----------|-----------------------------------------------------|
| `title`                      | string        | Yes      | Title of the issue. GitLab Self-Managed only.       |
| `assignee_ids`               | integer array | No       | IDs of the users to assign the issue to. Ultimate only. |
| `confidential`               | boolean       | No       | Sets the issue to confidential. Default is `false`. |

Rendered example:

For information about writing attribute descriptions, see the GraphQL API description style guide.

Conditionally required attributes

If there are attributes where either one or both are required to make an API request:

1. Add Conditionally in the Required column.

2. Clearly describe the related attributes in the description. You can use the following template:

   At least one of `attribute1` or `attribute2` must be included in the API call. Both may be used if needed.

For example:

Response body description

Start the description with the following sentence, replacing status code with the relevant HTTP status code, for example:

If successful, returns [`200 OK`](../../api/rest/troubleshooting.md#status-codes) and the
following response attributes:

Use the following table headers to describe the response bodies. Attributes should always be in code blocks using backticks (`).

If the attribute is a complex type, like another object, represent sub-attributes with dots (.), like project.name or projects[].name in case of an array.

Sort the table alphabetically.

| Attribute                    | Type          | Description                               |
|------------------------------|---------------|-------------------------------------------|
| `assignee_ids`               | integer array | IDs of the users to assign the issue to. Premium and Ultimate only. |
| `confidential`               | boolean       | Whether the issue is confidential or not. |
| `title`                      | string        | Title of the issue.                       |

Rendered example:

For information about writing attribute descriptions, see the GraphQL API description style guide.

cURL commands

• Use https://gitlab.example.com/api/v4/ as an endpoint.
• Wherever needed use this personal access token: <your_access_token>.
• Always put the request first. GET is the default so you don’t have to include it.
• Use long option names (--header instead of -H) for legibility. (Tested in scripts/lint-doc.sh.)
• Declare URLs with the --url parameter, and wrap the URL in double quotes (").
• Prefer to use examples using the personal access token and don’t pass data of username and password.
• For legibility, use the \ character and indentation to break long single-line commands apart into multiple lines.

cURL Examples

The following sections include a set of cURL examples you can use in the API documentation.

Simple cURL command

Get the details of a group:

curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/gitlab-org"

cURL example with parameters passed in the URL

Create a new project under the authenticated user’s namespace:

curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects?name=foo"

Post data using cURL’s --data

Instead of using --request POST and appending the parameters to the URI, you can use cURL’s --data option. The example below will create a new project foo under the authenticated user’s namespace.

curl --data "name=foo" \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects"

Post data using JSON content

This example creates a new group. Be aware of the use of single (') and double (") quotes.

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --header "Content-Type: application/json" \
  --data '{"path": "my-group", "name": "My group"}' \
  --url "https://gitlab.example.com/api/v4/groups"

For readability, you can also set up the --data by using the following format:

curl --request POST \
  --url "https://gitlab.example.com/api/v4/groups" \
  --header "content-type: application/json" \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --data '{
    "path": "my-group",
    "name": "My group"
}'

Post data using form-data

Instead of using JSON or URL-encoding data, you can use multipart/form-data which properly handles data encoding:

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --form "title=ssh-key" \
  --form "key=ssh-rsa AAAAB3NzaC1yc2EA..." \
  --url "https://gitlab.example.com/api/v4/users/25/keys"

The above example adds an SSH public key titled ssh-key to the account of a user with ID 25. The operation requires administrator access.

Escape special characters

Spaces or slashes (/) can sometimes result in errors, so you should escape them when possible. In the example below we create a new issue which contains spaces in its title. Observe how spaces are escaped using the %20 ASCII code.

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/42/issues?title=Hello%20GitLab"

Use %2F for slashes (/).

Pass arrays to API calls

The GitLab API sometimes accepts arrays of strings or integers. For example, to exclude specific users when requesting a list of users for a project, you would do something like this:

curl --request PUT \
  --header "PRIVATE-TOKEN: <your_access_token>"
  --data "skip_users[]=<user_id>" \
  --data "skip_users[]=<user_id>" \
  --url "https://gitlab.example.com/api/v4/projects/<project_id>/users"