トピックス API

GitLab 14.5 で導入されました。

REST API を使ってプロジェクトトピックと対話します。

トピックの一覧

GitLab インスタンス内のプロジェクトトピックの一覧を、関連するプロジェクトの数順に返します。

GET /topics

サポートされる属性：

属性種類必須説明
page整数。 {点線円｝いいえ取得するページ。デフォルトは1 。
per_page整数。 {点線円｝いいえページごとに返すレコード数。デフォルトは20 です。
search文字列です。 {点線円｝いいえ name からトピックを検索します。
without_projectsboolean {点線円｝いいえプロジェクトが割り当てられていないトピックに結果を限定します。

リクエストの例

curl "https://gitlab.example.com/api/v4/topics?search=git"

応答例

[
  {
    "id": 1,
    "name": "gitlab",
    "title": "GitLab",
    "description": "GitLab is an open source end-to-end software development platform with built-in version control, issue tracking, code review, CI/CD, and more.",
    "total_projects_count": 1000,
    "avatar_url": "http://www.gravatar.com/avatar/a0d477b3ea21970ce6ffcbb817b0b435?s=80&d=identicon"
  },
  {
    "id": 3,
    "name": "git",
    "title": "Git",
    "description": "Git is a free and open source distributed version control system designed to handle everything from small to very large projects with speed and efficiency.",
    "total_projects_count": 900,
    "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon"
  },
  {
    "id": 2,
    "name": "git-lfs",
    "title": "Git LFS",
    "description": null,
    "total_projects_count": 300,
    "avatar_url": null
  }
]

トピックの取得

プロジェクトのトピックをIDで取得します。

GET /topics/:id

サポートされる属性：

属性種類必須説明
id整数。 {チェックサークル｝はいプロジェクトトピックのID

リクエストの例

curl "https://gitlab.example.com/api/v4/topics/1"

応答例

{
  "id": 1,
  "name": "gitlab",
  "title": "GitLab",
  "description": "GitLab is an open source end-to-end software development platform with built-in version control, issue tracking, code review, CI/CD, and more.",
  "total_projects_count": 1000,
  "avatar_url": "http://www.gravatar.com/avatar/a0d477b3ea21970ce6ffcbb817b0b435?s=80&d=identicon"
}

トピックに割り当てられたプロジェクトのリスト

特定のトピックに割り当てられているすべてのプロジェクトを一覧表示するには、Projects API を使用します。

GET /projects?topic=<topic_name>

プロジェクトトピックの作成

新しいプロジェクトトピックを作成します。管理者のみ使用できます。

POST /topics

サポートされる属性：

属性種類必須説明
name文字列です。 {チェックサークル｝はいスラッグ (名前)
title文字列です。 {チェックサークル｝はいタイトル
avatarファイル {点線円｝いいえアバター
description文字列です。 {点線円｝いいえ説明

リクエストの例

curl --request POST \
     --data "name=topic1&title=Topic 1" \
     --header "PRIVATE-TOKEN: <your_access_token>" \
     "https://gitlab.example.com/api/v4/topics"

応答例

{
  "id": 1,
  "name": "topic1",
  "title": "Topic 1",
  "description": null,
  "total_projects_count": 0,
  "avatar_url": null
}

プロジェクトトピックの更新

プロジェクトのトピックを更新します。管理者のみ利用可能です。

PUT /topics/:id

サポートされる属性：

属性種類必須説明
id整数。 {チェックサークル｝はいプロジェクトトピックのID
avatarファイル {点線円｝いいえアバター
description文字列です。 {点線円｝いいえ説明
name文字列です。 {点線円｝いいえスラッグ (名前)
title文字列です。 {点線円｝いいえタイトル

リクエストの例

curl --request PUT \
     --data "name=topic1" \
     --header "PRIVATE-TOKEN: <your_access_token>" \
     "https://gitlab.example.com/api/v4/topics/1"

応答例

{
  "id": 1,
  "name": "topic1",
  "title": "Topic 1",
  "description": null,
  "total_projects_count": 0,
  "avatar_url": null
}

トピックアバターのアップロード

ファイルシステムからアバターファイルをアップロードするには、--form 引数を使用します。この引数により、cURL はヘッダContent-Type: multipart/form-dataを使用してデータを投稿します。file= パラメータはファイルシステム上のファイルを指し、その前に@を付ける必要があります。例えば

curl --request PUT \
     --header "PRIVATE-TOKEN: <your_access_token>" \
     "https://gitlab.example.com/api/v4/topics/1" \
     --form "avatar=@/tmp/example.png"

トピックアバターの削除

GitLab 14.6で導入されました。

トピックのアバターを削除するには、avatar 属性に空白を指定してください。

リクエストの例

curl --request PUT \
     --data "avatar=" \
     --header "PRIVATE-TOKEN: <your_access_token>" \
     "https://gitlab.example.com/api/v4/topics/1"

プロジェクトトピックの削除

GitLab 14.9で導入されました。

プロジェクトトピックを削除するには、管理者である必要があります。プロジェクトトピックを削除すると、プロジェクトのトピックの割り当ても削除されます。

DELETE /topics/:id

サポートされる属性：

属性種類必須説明
id整数。 {チェックサークル｝はいプロジェクトトピックのID

リクエストの例

curl --request DELETE \
     --header "PRIVATE-TOKEN: <your_access_token>" \
     "https://gitlab.example.com/api/v4/topics/1"

トピックのマージ

GitLab 15.4で導入されました。

ソーストピックをターゲットトピックにマージするには、管理者である必要があります。トピックをマージすると、ソーストピックは削除され、割り当てられたプロジェクトはすべてターゲットトピックに移動します。

POST /topics/merge

サポートされる属性：

属性種類必須説明
source_topic_id整数。 {チェックサークル｝はいソースプロジェクトトピックのID
target_topic_id整数。 {チェックサークル｝はい対象プロジェクトトピックのID

リクエストの例

curl --request POST \
     --data "source_topic_id=2&target_topic_id=1" \
     --header "PRIVATE-TOKEN: <your_access_token>" \
     "https://gitlab.example.com/api/v4/topics/merge"

応答例

{
  "id": 1,
  "name": "topic1",
  "title": "Topic 1",
  "description": null,
  "total_projects_count": 0,
  "avatar_url": null
}