debian-mirror-gitlab/doc/development/documentation/restful_api_styleguide.md

Ignoring revisions in .git-blame-ignore-revs. Click here to bypass and see the normal blame view.

292 lines
12 KiB
Markdown
Raw Normal View History

2021-01-03 14:25:43 +05:30
---
2022-01-26 12:08:38 +05:30
info: For assistance with this Style Guide page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments-to-other-projects-and-subjects.
2022-03-02 08:16:31 +05:30
stage: none
group: unassigned
2022-01-26 12:08:38 +05:30
description: 'Writing styles, markup, formatting, and other standards for the GitLab RESTful APIs.'
2021-01-03 14:25:43 +05:30
---
# RESTful API
REST API resources are documented in Markdown under
[`/doc/api`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/doc/api). Each
resource has its own Markdown file, which is linked from `api_resources.md`.
When modifying the Markdown, also update the corresponding
[OpenAPI definition](https://gitlab.com/gitlab-org/gitlab/-/tree/master/doc/api/openapi)
if one exists for the resource. If not, consider creating one. Match the latest
[OpenAPI 3.0.x specification](https://swagger.io/specification/). (For more
information, see the discussion in this
[issue](https://gitlab.com/gitlab-org/gitlab/-/issues/16023#note_370901810).)
In the Markdown doc for a resource (AKA endpoint):
- Every method must have the REST API request. For example:
```plaintext
GET /projects/:id/repository/branches
```
2022-07-16 23:28:13 +05:30
- Every method must have a detailed [description of the attributes](#method-description).
2021-01-03 14:25:43 +05:30
- Every method must have a cURL example.
2022-07-16 23:28:13 +05:30
- Every method must have a detailed [description of the response body](#response-body-description).
- Every method must have a response body example (in JSON format).
2022-01-26 12:08:38 +05:30
- If an attribute is available only to higher level tiers than the other
2022-07-16 23:28:13 +05:30
attributes, add the appropriate inline [tier badge](styleguide/index.md#product-tier-badges).
2022-01-26 12:08:38 +05:30
Put the badge in the **Attribute** column, like the
`**(<tier>)**` code in the following template.
2021-01-03 14:25:43 +05:30
## API topic template
2021-09-04 01:27:46 +05:30
Use the following template to help you get started. Be sure to list any
required attributes first in the table.
2021-01-03 14:25:43 +05:30
````markdown
2022-07-23 23:45:48 +05:30
## API name
2021-01-03 14:25:43 +05:30
2021-01-29 00:20:46 +05:30
> Version history note.
2021-01-03 14:25:43 +05:30
One or two sentence description of what endpoint does.
2022-07-23 23:45:48 +05:30
### Method title
> Version history note.
Description of the method.
2021-01-03 14:25:43 +05:30
```plaintext
METHOD /endpoint
```
2021-01-29 00:20:46 +05:30
Supported attributes:
2022-01-26 12:08:38 +05:30
| Attribute | Type | Required | Description |
|:-------------------------|:---------|:-----------------------|:----------------------|
| `attribute` | datatype | **{check-circle}** Yes | Detailed description. |
| `attribute` **(<tier>)** | datatype | **{dotted-circle}** No | Detailed description. |
| `attribute` | datatype | **{dotted-circle}** No | Detailed description. |
| `attribute` | datatype | **{dotted-circle}** No | Detailed description. |
2021-01-03 14:25:43 +05:30
2022-07-16 23:28:13 +05:30
Response body attributes:
| Attribute | Type | Description |
|:-------------------------|:---------|:----------------------|
| `attribute` | datatype | Detailed description. |
| `attribute` **(<tier>)** | datatype | Detailed description. |
2021-01-03 14:25:43 +05:30
Example request:
```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/endpoint?parameters"
```
Example response:
```json
[
{
}
]
```
````
2022-07-23 23:45:48 +05:30
## Version history
Add [version history](versions.md#documenting-version-specific-features)
to describe new or updated API calls.
To add version history for an individual attribute, include it in the version history
for the section. For example:
```markdown
### Edit a widget
> `widget_message` [introduced](<link-to-issue>) in GitLab 14.3.
```
## Attribute deprecation
To deprecate an attribute:
1. Add a version history note.
```markdown
> - `widget_name` [deprecated](<link-to-issue>) in GitLab 14.7.
```
1. Add inline deprecation text to the description.
```markdown
| Attribute | Type | Required | Description |
|:--------------|:-------|:-----------------------|:----------------------------------------------------------------------------------------------------------------------------------------------------|
| `widget_name` | string | **{dotted-circle}** No | [Deprecated](<link-to-issue>) in GitLab 14.7 and is planned for removal in 15.4. Use `widget_id` instead. The name of the widget. |
```
1. Optional. To widely announce the change, or if it's a breaking change,
[update the deprecations and removals documentation](../deprecation_guidelines/#update-the-deprecations-and-removals-documentation).
2021-01-29 00:20:46 +05:30
2021-01-03 14:25:43 +05:30
## Method description
Use the following table headers to describe the methods. Attributes should
always be in code blocks using backticks (`` ` ``).
2022-06-21 17:19:12 +05:30
Sort the table by required attributes first, then alphabetically.
2021-12-11 22:18:48 +05:30
2021-01-03 14:25:43 +05:30
```markdown
2022-07-16 23:28:13 +05:30
| Attribute | Type | Required | Description |
|:-----------------------------|:--------------|:-----------------------|:----------------------------------------------------|
2022-06-21 17:19:12 +05:30
| `title` | string | **{check-circle}** Yes | Title of the issue. |
2022-07-16 23:28:13 +05:30
| `assignee_ids` **(PREMIUM)** | integer array | **{dotted-circle}** No | IDs of the users to assign the issue to. |
2022-06-21 17:19:12 +05:30
| `confidential` | boolean | **{dotted-circle}** No | Sets the issue to confidential. Default is `false`. |
2021-01-03 14:25:43 +05:30
```
Rendered example:
2022-07-16 23:28:13 +05:30
| Attribute | Type | Required | Description |
|:-----------------------------|:--------------|:-----------------------|:----------------------------------------------------|
2022-06-21 17:19:12 +05:30
| `title` | string | **{check-circle}** Yes | Title of the issue. |
2022-07-16 23:28:13 +05:30
| `assignee_ids` **(PREMIUM)** | integer array | **{dotted-circle}** No | IDs of the users to assign the issue to. |
2022-06-21 17:19:12 +05:30
| `confidential` | boolean | **{dotted-circle}** No | Sets the issue to confidential. Default is `false`. |
For information about writing attribute descriptions, see the [GraphQL API description style guide](../api_graphql_styleguide.md#description-style-guide).
2021-01-03 14:25:43 +05:30
2022-07-16 23:28:13 +05:30
## Response body description
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.
```markdown
| Attribute | Type | Description |
|:-----------------------------|:--------------|:------------------------------------------|
| `assignee_ids` **(PREMIUM)** | integer array | IDs of the users to assign the issue to. |
| `confidential` | boolean | Whether the issue is confidential or not. |
| `title` | string | Title of the issue. |
```
Rendered example:
| Attribute | Type | Description |
|:-----------------------------|:--------------|:------------------------------------------|
| `assignee_ids` **(PREMIUM)** | integer array | IDs of the users to assign the issue to. |
| `confidential` | boolean | Whether the issue is confidential or not. |
| `title` | string | Title of the issue. |
For information about writing attribute descriptions, see the [GraphQL API description style guide](../api_graphql_styleguide.md#description-style-guide).
2021-01-03 14:25:43 +05:30
## 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.
- Wrap the URL in double quotes (`"`).
- Prefer to use examples using the personal access token and don't pass data of
username and password.
2021-12-11 22:18:48 +05:30
| Methods | Description |
2022-01-26 12:08:38 +05:30
|:------------------------------------------------|:-------------------------------------------------------|
2021-01-03 14:25:43 +05:30
| `--header "PRIVATE-TOKEN: <your_access_token>"` | Use this method as is, whenever authentication needed. |
2022-07-16 23:28:13 +05:30
| `--request POST` | Use this method when creating new objects. |
| `--request PUT` | Use this method when updating existing objects. |
| `--request DELETE` | Use this method when removing existing objects. |
2021-01-03 14:25:43 +05:30
## cURL Examples
2021-02-22 17:27:13 +05:30
The following sections include a set of [cURL](https://curl.se/) examples
2021-01-03 14:25:43 +05:30
you can use in the API documentation.
2021-02-22 17:27:13 +05:30
WARNING:
2021-01-03 14:25:43 +05:30
Do not use information for real users, URLs, or tokens. For documentation, refer to our
2021-01-29 00:20:46 +05:30
relevant style guide sections on [Fake user information](styleguide/index.md#fake-user-information),
[Fake URLs](styleguide/index.md#fake-urls), and [Fake tokens](styleguide/index.md#fake-tokens).
2021-01-03 14:25:43 +05:30
### Simple cURL command
Get the details of a group:
```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "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:
```shell
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "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.
```shell
curl --data "name=foo" --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects"
```
### Post data using JSON content
2021-01-29 00:20:46 +05:30
This example creates a new group. Be aware of the use of single (`'`) and double
(`"`) quotes.
2021-01-03 14:25:43 +05:30
```shell
2021-09-04 01:27:46 +05:30
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --header "Content-Type: application/json" \
--data '{"path": "my-group", "name": "My group"}' "https://gitlab.example.com/api/v4/groups"
2021-01-03 14:25:43 +05:30
```
2021-01-29 00:20:46 +05:30
For readability, you can also set up the `--data` by using the following format:
```shell
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"
}'
```
2021-01-03 14:25:43 +05:30
### Post data using form-data
2021-03-11 19:13:27 +05:30
Instead of using JSON or URL-encoding data, you can use `multipart/form-data` which
2021-01-03 14:25:43 +05:30
properly handles data encoding:
```shell
2021-09-04 01:27:46 +05:30
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --form "title=ssh-key" \
--form "key=ssh-rsa AAAAB3NzaC1yc2EA..." "https://gitlab.example.com/api/v4/users/25/keys"
2021-01-03 14:25:43 +05:30
```
The above example is run by and administrator and will add an SSH public key
titled `ssh-key` to user's account which has an ID of 25.
### Escape special characters
Spaces or slashes (`/`) may sometimes result to errors, thus it is recommended
to 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.
```shell
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/42/issues?title=Hello%20Dude"
```
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:
```shell
2021-09-04 01:27:46 +05:30
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" --data "skip_users[]=<user_id>" \
--data "skip_users[]=<user_id>" "https://gitlab.example.com/api/v4/projects/<project_id>/users"
2021-01-03 14:25:43 +05:30
```