REST APIリソースの文書化

REST APIリソースは、/doc/apiの下でMarkdownで文書化されています。各リソースには独自のMarkdownファイルがあり、api_resources.mdからリンクされています。

Markdownを修正するとき、リソースに対応するOpenAPI定義があれば、それも更新してください。存在しない場合は、作成を検討してください。最新のOpenAPI 3.0.x 仕様に合わせましょう。(詳細については、このイシューの説明を参照してください)。

リソース（別名エンドポイント）のMarkdownドキュメントで：

すべてのメソッドはREST APIリクエストを持っていなければなりません。例えば
```
 GET /projects/:id/repository/branches
```
すべてのメソッドには、属性の詳細な説明が必要です。
すべてのメソッドには cURL の例が必要です。
すべてのメソッドには、レスポンスボディの詳細な説明が必要です。
すべてのメソッドには、(JSON形式の)レスポンスボディの例がなければなりません。
ある属性が他の属性よりも上位階層でのみ利用可能な場合、適切なインライン階層バッジを追加します。次のテンプレートの**(<tier>)** コードのように、バッジをAttribute列に記述します。

新しいAPIドキュメント・ページが追加されたら、グローバル・ナビゲーションにエントリを追加します。例

APIトピックテンプレート

以下のテンプレートを使用してください。必須属性は必ず最初に表に記載してください。

## API name

> Version history note.

One or two sentence description of what endpoint does.

### Method title

> Version history note.

Description of the method.

```plaintext
METHOD /endpoint
```

Supported attributes:

| Attribute                | Type     | Required | Description           |
|--------------------------|----------|----------|-----------------------|
| `attribute`              | datatype | Yes      | Detailed description. |
| `attribute` **(<tier>)** | datatype | No       | Detailed description. |
| `attribute`              | datatype | No       | Detailed description. |
| `attribute`              | datatype | No       | Detailed description. |

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

| Attribute                | Type     | Description           |
|--------------------------|----------|-----------------------|
| `attribute`              | datatype | Detailed description. |
| `attribute` **(<tier>)** | 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
[
  {
  }
]
```

バージョン履歴

新しいAPIコールや更新されたAPIコールを説明するためにバージョン履歴を追加します。

個々の属性のバージョン履歴を追加するには、セクションのバージョン履歴にその属性を含めます。例えば

### Edit a widget

> `widget_message` [introduced](<link-to-issue>) in GitLab 14.3.

API や属性が機能フラグの後ろにデプロイされている場合、機能フラグの情報をバージョン履歴に含めます。

非推奨事項

API エンドポイントの非推奨を文書化するには、ページまたはトピックを非推奨にする手順に従ってください。

属性を非推奨にするには

バージョン履歴ノートを追加します。

> - `widget_name` [deprecated](<link-to-issue>) in GitLab 14.7.

説明にインライン非推奨テキストを追加。

| Attribute     | Type   | Required | Description |
|---------------|--------|----------|-------------|
| `widget_name` | string | 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. |

非推奨を広くアナウンスするため、またはそれが破壊的な変更である場合は、REST API の非推奨と削除のページを更新してください。

メソッドの説明

メソッドの説明には、以下の表ヘッダを使用してください。属性は常に、バックティック (`) を使用したコードブロック内に記述してください。

表は、最初に必須属性、次にアルファベット順に並べ替えます。

| Attribute                    | Type          | Required | Description                                         |
|------------------------------|---------------|----------|-----------------------------------------------------|
| `title`                      | string        | Yes      | Title of the issue.                                 |
| `assignee_ids` **(PREMIUM ALL)** | integer array | No       | IDs of the users to assign the issue to.            |
| `confidential`               | boolean       | No       | Sets the issue to confidential. Default is `false`. |

レンダリング例：

属性	種類	必須	説明
`title`	文字列です。	はい	イシューのタイトル。
`assignee_ids`	整数配列。	なし	イシューを割り当てるユーザーのID。
`confidential`	boolean	なし	イシューを機密扱いに設定します。デフォルトは`false` です。

属性の説明の記述については、GraphQL API 説明スタイルガイドを参照してください。

レスポンス本体の説明

status code を関連するHTTP ステータスコードに置き換えてください：

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

レスポンス・ボディを記述するには、以下のテーブル・ヘッダを使用してください。属性は常にバックスティック(`)を使ったコードブロック内に記述してください。

属性が他のオブジェクトのような複合型の場合は、配列の場合はproject.name やprojects[].name のように、サブ属性をドット (.) で表します。

表をアルファベット順に並べ替えます。

| Attribute                    | Type          | Description                               |
|------------------------------|---------------|-------------------------------------------|
| `assignee_ids` **(PREMIUM ALL)** | 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.                       |

レンダリング例：

属性	種類	説明
`assignee_ids`	整数配列。	イシューを割り当てるユーザーのID。
`confidential`	boolean	イシューが機密かどうか。
`title`	文字列です。	イシューのタイトル。

属性の説明の記述については、GraphQL API 説明スタイルガイドを参照してください。

cURLコマンド

https://gitlab.example.com/api/v4/ をエンドポイントとして使用します。
必要な場合は、この個人アクセストークンを使用してください:<your_access_token> 。
GET がデフォルトなので、これを含める必要はありません。
読みやすくするために長いオプション名 (-H の代わりに--header ) を使ってください。(scripts/lint-doc.shでテスト済み)。
URLを--url パラメータで宣言し、ダブルクォーテーション(")で囲みます。
個人アクセストークンを使用する例を優先し、ユーザー名とパスワードのデータを渡さないようにしてください。
読みやすくするために、 ㊟ 文字とインデントを使用して、長い1行のコマンドを複数行に分割してください。

方法	説明
`--header "PRIVATE-TOKEN: <your_access_token>"`	認証が必要な場合は、このメソッドをそのまま使用します。
`--request POST`	新しいオブジェクトを作成するときは、このメソッドを使用します。
`--request PUT`	既存のオブジェクトを更新する場合は、このメソッドを使用します。
`--request DELETE`	既存のオブジェクトを削除する場合は、このメソッドを使用します。

cURL の例

以下のセクションには、APIドキュメントで使用できる一連のcURL例が含まれています。

本物のユーザー、URL、トークンの情報は使用しないでください。ドキュメントについては、スタイルガイドの「偽のユーザー情報」、「偽のURL」、「偽のトークン」に関連するセクションを参照してください。

簡単なcURLコマンド

グループの詳細を取得します：

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

URL にパラメータを渡した場合の cURL の例

認証ユーザーのネームスペースで新しいプロジェクトを作成します：

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

cURLの`--data`

--request POST を使用してパラメータを URI に追加する代わりに、cURL の--data オプションを使用することができます。以下の例では、認証ユーザーのネームスペースの下に新しいプロジェクトfoo を作成します。

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

JSONコンテンツを使ってデータを投稿

この例では、新しいグループを作成します。シングルクォート (') とダブルクォート (") の使用に注意してください。

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"

読みやすくするために、--data を次のような形式で設定することもできます：

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"
}'

フォームデータを使ってデータを投稿

JSONやURLエンコーディングのデータを使う代わりに、multipart/form-data ：

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"

上の例は管理者によって実行され、ssh-key というタイトルの SSH 公開鍵を ID が 25 のユーザーのアカウントに追加します。

特殊文字のエスケープ

スペースやスラッシュ(/)はエラーの原因となることがあるため、可能な限りエスケープすることをお勧めします。以下の例では、タイトルにスペースを含む新しいイシューを作成します。%20 ASCIIコードを使用してスペースがどのようにエスケープされるかを確認してください。

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

スラッシュ (/) には%2F を使用してください。

API 呼び出しに配列を渡す

GitLab API では文字列や整数の配列を受け付けることがあります。たとえば、あるプロジェクトのユーザー一覧を要求する際に特定のユーザーを除外するには次のようにします：

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"

REST APIリソースの文書化

APIトピックテンプレート

バージョン履歴

非推奨事項

メソッドの説明

レスポンス本体の説明

cURLコマンド

cURL の例

簡単なcURLコマンド

URL にパラメータを渡した場合の cURL の例

cURLの`--data`

JSONコンテンツを使ってデータを投稿

フォームデータを使ってデータを投稿

特殊文字のエスケープ

API 呼び出しに配列を渡す

Help & feedback

Docs

Product

Feature availability and product trials

Get Help

REST APIリソースの文書化

APIトピックテンプレート

バージョン履歴

非推奨事項

メソッドの説明

レスポンス本体の説明

cURLコマンド

cURL の例

簡単なcURLコマンド

URL にパラメータを渡した場合の cURL の例

cURLの--data

JSONコンテンツを使ってデータを投稿

フォームデータを使ってデータを投稿

特殊文字のエスケープ

API 呼び出しに配列を渡す

Help & feedback

Docs

Product

Feature availability and product trials

Get Help

cURLの`--data`