REST API

プラン: Free、Premium、Ultimate
提供形態: GitLab.com、GitLab Self-Managed、GitLab Dedicated

GitLab REST APIを使用してワークフローを自動化し、インテグレーションを構築します:

手動操作なしで、GitLabリソースを大規模に管理するカスタムツールを作成します。
GitLabデータをアプリケーションに直接統合することで、コラボレーションを向上させます。
複数のプロジェクトにわたって、CI/CDプロセスを正確に管理します。
プログラムでユーザーアクセスを制御して、組織全体で一貫した権限を維持します。

REST APIでは、既存のツールやシステムとの互換性のために、標準のHTTPメソッドとJSONデータ形式が使用されます。

REST APIリクエストを実行する

REST APIリクエストを実行するには、次のようにします:

REST APIクライアントを使用して、APIエンドポイントにリクエストを送信します。
GitLabインスタンスがリクエストに応答します。ステータスコードと、該当する場合はリクエストされたデータが返されます。ステータスコードはリクエストの結果を示し、トラブルシューティングの際に役立ちます。

REST APIリクエストは、ルートエンドポイントとパスで始まる必要があります。

ルートエンドポイントはGitLabホスト名です。
パスは/api/v4で始まる必要があります（v4はAPIバージョンを表します）。

次の例では、APIリクエストでGitLabホスト（gitlab.example.com）上のすべてのプロジェクトのリストを取得します:

curl --request GET \
  --url "https://gitlab.example.com/api/v4/projects"

一部のエンドポイントへのアクセスには認証が必要です。詳細については、認証を参照してください。

レート制限

REST APIリクエストはレート制限設定の対象となります。この設定はGitLabインスタンスのオーバーロードのリスクを軽減するためのものです。

詳細については、レート制限を参照してください。
GitLab.comで使用されるレート制限設定の詳細については、GitLab.com固有のレート制限を参照してください。

応答形式

REST APIの応答はJSON形式で返されます。一部のAPIエンドポイントは、プレーンテキスト形式もサポートしています。エンドポイントでサポートされるコンテンツタイプを確認するには、REST APIリソースを参照してください。

リクエスト要件

一部のREST APIリクエストには、使用するデータ形式やエンコードなど、特定の要件があります。

リクエストペイロード

APIリクエストでは、クエリ文字列またはペイロード本文として送信されるパラメータを使用できます。通常、GETリクエストはクエリ文字列を送信し、PUTリクエストまたはPOSTリクエストはペイロード本文を送信します:

クエリ文字列:

curl --request POST \
  --url "https://gitlab.example.com/api/v4/projects?name=<example-name>&description=<example-description>"

リクエストペイロード（JSON）:

curl --request POST \
  --header "Content-Type: application/json" \
  --data '{"name":"<example-name>", "description":"<example-description>"}' "https://gitlab.example.com/api/v4/projects"

URLエンコードされたクエリ文字列の長さには制限があります。リクエストが大きすぎると、414 Request-URI Too Largeというエラーメッセージが生成されます。これは、代わりにペイロード本文を使用することで解決できます。

パスパラメータ

エンドポイントにパスパラメータがある場合、ドキュメントでは先頭にコロンを付けて表示します。

例:

DELETE /projects/:id/share/:group_id

:idパスパラメータはプロジェクトIDに、:group_idはグループのIDに置き換える必要があります。コロン（:）は含めないでください。

ID 5のプロジェクトとID 17のグループに対して送信するcURLリクエストは次のようになります:

curl --request DELETE \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/share/17"

パスパラメータでURLエンコードが必要なら、その形式に従う必要があります。そうでない場合、APIエンドポイントと一致せず、404エラーが返されます。APIの前に何か（Apacheなど）がある場合、それがURLエンコードされたパスパラメータをデコードしないことを確認してください。

`id`と`iid`の違い

一部のAPIリソースには、類似する名前のフィールドが2つあります。たとえば、イシュー、マージリクエスト、プロジェクトのマイルストーンなどです。これらのフィールドを以下に示します:

id: すべてのプロジェクトで一意のID。
iid: 追加の内部ID（Web UIに表示）。単一プロジェクトのスコープ内で一意。

リソースにiidフィールドとidフィールドの両方がある場合、通常はリソースをフェッチするためにidフィールドではなくiidフィールドが使用されます。

たとえば、id: 42のプロジェクトにid: 46とiid: 5のイシューがあるとします。この場合、次のようになります:

イシューを取得するための有効なAPIリクエストはGET /projects/42/issues/5です。
イシューを取得するための無効なAPIリクエストはGET /projects/42/issues/46です。

iidフィールドを持つすべてのリソースがiidによってフェッチされるわけではありません。どのフィールドを使用すべきかについては、特定のリソースのドキュメントを参照してください。

エンコード

REST APIリクエストを実行する場合、特殊文字とデータ構造を考慮して一部のコンテンツをエンコードする必要があります。

ネームスペース付きのパス

ネームスペース付きのAPIリクエストを使用する場合は、NAMESPACE/PROJECT_PATHがURLエンコードされていることを確認してください。

たとえば、/は%2Fで表されます:

GET /api/v4/projects/diaspora%2Fdiaspora

プロジェクトのパスは、必ずしもその名前と同じではありません。プロジェクトのパスは、プロジェクトのURLまたはプロジェクトの設定の一般 > 高度な設定 > パスを変更にあります。

ファイルパス、ブランチ、タグ名

ファイルパス、ブランチ、またはタグに/が含まれている場合は、URLエンコードされていることを確認してください。

たとえば、/は%2Fで表されます:

GET /api/v4/projects/1/repository/files/src%2FREADME.md?ref=master
GET /api/v4/projects/1/branches/my%2Fbranch/commits
GET /api/v4/projects/1/repository/tags/my%2Ftag

array（配列）型とhash（ハッシュ）型

array型とhash型のパラメータを使用してAPIをリクエストできます:

`array`

import_sourcesはarray型のパラメータです:

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  -d "import_sources[]=github" \
  -d "import_sources[]=bitbucket" \
  --url "https://gitlab.example.com/api/v4/some_endpoint"

`hash`

override_paramsはhash型のパラメータです:

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --form "namespace=email" \
  --form "path=impapi" \
  --form "file=@/path/to/somefile.txt" \
  --form "override_params[visibility]=private" \
  --form "override_params[some_other_param]=some_value" \
  --url "https://gitlab.example.com/api/v4/projects/import"

ハッシュの配列

variablesは、ハッシュのキー/値ペア[{ 'key': 'UPLOAD_TO_S3', 'value': 'true' }]を含むarray型のパラメータです:

curl --globoff --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/169/pipeline?ref=master&variables[0][key]=VAR1&variables[0][value]=hello&variables[1][key]=VAR2&variables[1][value]=world"

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --header "Content-Type: application/json" \
  --data '{ "ref": "master", "variables": [ {"key": "VAR1", "value": "hello"}, {"key": "VAR2", "value": "world"} ] }' \
  --url "https://gitlab.example.com/api/v4/projects/169/pipeline"

ISO 8601形式の日付での`+`のエンコード

W3の推奨事項によって+がスペースとして解釈されることから、クエリパラメータに+を含める必要がある場合は、代わりに%2Bを使用する必要があります。たとえば、ISO 8601形式の日付で特定の時刻を含める場合、次のようになります:

2017-10-17T23:11:13.000+05:30

クエリパラメータの正しいエンコードは次のようになります:

2017-10-17T23:11:13.000%2B05:30

応答の評価

状況によっては、API応答が予想どおりにならない場合があります。可能性のある問題としては、null値やリダイレクトなどがあります。応答で数値のステータスコードを受け取った場合は、ステータスコードを参照してください。

`null`と`false`の違い

API応答では、一部のブール値フィールドにnull値が含まれる場合があります。nullブール値はデフォルト値がなく、trueでもfalseでもありません。GitLabは、ブール値フィールドのnull値をfalseと同様に扱います。

ブール値引数に設定する値は、trueかfalseの値だけです（nullではありません）。

リダイレクト

パスの変更後、REST APIはエンドポイントが移動したことを示すメッセージで応答することがあります。この場合、Locationヘッダーに指定されたエンドポイントを使用してください。

別のパスに移動したプロジェクトの例:

curl --request GET \
  --verbose \
  --url "https://gitlab.example.com/api/v4/projects/gitlab-org%2Fold-path-project"

応答は次のようになります:

...
< Location: http://gitlab.example.com/api/v4/projects/81
...
This resource has been moved permanently to https://gitlab.example.com/api/v4/projects/81

ページネーション

GitLabは、次のページネーション方法をサポートしています:

オフセットベースのページネーション。デフォルトの方法であり、GitLab 16.5以降で、usersエンドポイントを除くすべてのエンドポイントで使用できます。
キーセットベースのページネーション。一部のエンドポイントに追加され、段階的にロールアウトされています。

大規模なコレクションの場合、パフォーマンス上の理由から、オフセットページネーションではなくキーセットページネーション（利用可能な場合）を使用してください。

オフセットベースのページネーション

usersエンドポイントは、GitLab 16.5でオフセットベースのページネーションでは非推奨になりました。17.0で削除される予定です。これは破壊的な変更です。代わりに、このエンドポイントにはキーセットベースのページネーションを使用してください。
GitLab 17.0では、リクエストされたレコード数が50,000を超える場合、usersエンドポイントでキーセットベースのページネーションが強制的に適用されます。

場合によっては、返される結果が複数のページにわたることがあります。リソースを一覧表示するときに、次のパラメータを渡すことができます:

パラメータ	説明
`page`	ページ番号（デフォルトは`1`）。
`per_page`	ページごとに表示するアイテム数（デフォルトは`20`、最大値は`100`）。

次の例では、ページごとに50個のネームスペースをリストします:

curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/namespaces?per_page=50"

オフセットページネーションには、最大許容オフセット制限があります。GitLab Self-Managedインスタンスでこの制限を変更できます。

ページネーション`Link`ヘッダー

Linkヘッダーは、各応答とともに返されます。このヘッダーでは、relがprev、next、first、lastのいずれかに設定されており、関連するURLが含まれています。独自のURLを生成するのではなく、必ずこれらのリンクを使用してください。

GitLab.comユーザーの場合、一部のページネーションヘッダーが返されないことがあります。

次のcURLの例では、出力をページあたり3アイテム（per_page=3）に制限し、プロジェクトID 9に属するID 8のイシューのコメントの2ページ目（page=2）をリクエストしています:

curl --request GET \
  --head \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/9/issues/8/notes?per_page=3&page=2"

応答は次のようになります:

HTTP/2 200 OK
cache-control: no-cache
content-length: 1103
content-type: application/json
date: Mon, 18 Jan 2016 09:43:18 GMT
link: <https://gitlab.example.com/api/v4/projects/8/issues/8/notes?page=1&per_page=3>; rel="prev", <https://gitlab.example.com/api/v4/projects/8/issues/8/notes?page=3&per_page=3>; rel="next", <https://gitlab.example.com/api/v4/projects/8/issues/8/notes?page=1&per_page=3>; rel="first", <https://gitlab.example.com/api/v4/projects/8/issues/8/notes?page=3&per_page=3>; rel="last"
status: 200 OK
vary: Origin
x-next-page: 3
x-page: 2
x-per-page: 3
x-prev-page: 1
x-request-id: 732ad4ee-9870-4866-a199-a9db0cde3c86
x-runtime: 0.108688
x-total: 8
x-total-pages: 3

その他のページネーションヘッダー

GitLabは、次のページネーションヘッダーも返します:

ヘッダー	説明
`x-next-page`	次のページのインデックス。
`x-page`	現在のページのインデックス（1から開始）。
`x-per-page`	ページあたりのアイテム数。
`x-prev-page`	前のページのインデックス。
`x-total`	アイテムの合計数。
`x-total-pages`	ページの合計数。

GitLab.comユーザーの場合、一部のページネーションヘッダーが返されないことがあります。

キーセットベースのページネーション

キーセットページネーションを使用すると、ページをより効率的に取得できるようになります。オフセットベースのページネーションとは対照的に、ランタイムはコレクションのサイズに依存しません。

この方法は次のパラメータで制御されます。order_byとsortはどちらも必須です。

パラメータ	必須	説明
`pagination`	はい	`keyset`（キーセットページネーションを有効にする）。
`per_page`	いいえ	ページごとに表示するアイテム数（デフォルトは`20`、最大値は`100`）。
`order_by`	はい	並べ替えの基準となる列。
`sort`	はい	並び替え順（`asc`または`desc`）

次の例では、projectsをページあたり50個、idの昇順で一覧表示します。

curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects?pagination=keyset&per_page=50&order_by=id&sort=asc"

応答ヘッダーには、次のページへのリンクが含まれています。例:

HTTP/1.1 200 OK
...
Link: <https://gitlab.example.com/api/v4/projects?pagination=keyset&per_page=50&order_by=id&sort=asc&id_after=42>; rel="next"
Status: 200 OK
...

次のページへのリンクには、すでに取得したレコードを除外する追加のフィルターid_after=42が含まれています。

別の例として、次のリクエストは、キーセットページネーションを使用して、グループをページあたり50個、nameの昇順で一覧表示します:

curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups?pagination=keyset&per_page=50&order_by=name&sort=asc"

応答ヘッダーには、次のページへのリンクが含まれています:

HTTP/1.1 200 OK
...
Link: <https://gitlab.example.com/api/v4/groups?pagination=keyset&per_page=50&order_by=name&sort=asc&cursor=eyJuYW1lIjoiRmxpZ2h0anMiLCJpZCI6IjI2IiwiX2tkIjoibiJ9>; rel="next"
Status: 200 OK
...

次のページへのリンクには、すでに取得したレコードを除外する追加のフィルターcursor=eyJuYW1lIjoiRmxpZ2h0anMiLCJpZCI6IjI2IiwiX2tkIjoibiJ9が含まれています。

フィルターの種類は、使用されるorder_byオプションによって異なります。また、複数の追加フィルターを設定できます。

Linksヘッダーは、W3CのLink仕様に対応するために削除されました。代わりにLinkヘッダーを使用する必要があります。

コレクションの末尾に達し、取得する追加のレコードがない場合には、Linkヘッダーは存在せず、結果の配列は空になります。

独自のURLを作成するのではなく、指定されたリンクのみを使用して次のページを取得する必要があります。表示されているヘッダー以外に、追加のページネーションヘッダーは公開されていません。

サポートされているリソース

キーセットベースのページネーションは、一部のリソースと並べ替えオプションでのみサポートされています:

リソース	オプション	利用可能
グループ監査イベント	`order_by=id`、`sort=desc`のみ	認証済みユーザーのみ。
グループ	`order_by=name`、`sort=asc`のみ	未認証ユーザーのみ。
インスタンス監査イベント	`order_by=id`、`sort=desc`のみ	認証済みユーザーのみ。
パッケージパイプライン	`order_by=id`、`sort=desc`のみ	認証済みユーザーのみ。
プロジェクトジョブ	`order_by=id`、`sort=desc`のみ	認証済みユーザーのみ。
プロジェクト監査イベント	`order_by=id`、`sort=desc`のみ	認証済みユーザーのみ。
プロジェクト	`order_by=id`のみ	認証済みユーザーおよび未認証ユーザー。
ユーザー	`order_by=id`、`order_by=name`、`order_by=username`、`order_by=created_at`、または`order_by=updated_at`。	認証済みユーザーおよび未認証ユーザー。GitLab 16.5で導入されました。
レジストリリポジトリタグ	`order_by=name`、`sort=asc`、または`sort=desc`のみ。	認証済みユーザーのみ。
リポジトリツリーをリストする	N/A	認証済みユーザーおよび未認証ユーザー。GitLab 17.1で導入されました。
プロジェクトイシュー	`order_by=created_at`、`order_by=updated_at`、`order_by=title`、`order_by=id`、`order_by=weight`、`order_by=due_date`、`order_by=relative_position`、`sort=asc`、または`sort=desc`のみ。	認証済みユーザーおよび未認証ユーザー。GitLab 18.3で導入されました。

ページネーション応答ヘッダー

パフォーマンス上の理由から、クエリが返すレコードの数が10,000件を超える場合、GitLabは次のヘッダーを返しません:

x-total。
x-total-pages。
rel="last" link

バージョニングと非推奨

REST APIのバージョンは、セマンティックバージョニング仕様に準拠しています。メジャーバージョン番号は4です。下位互換性のない変更の場合、このバージョン番号を変更する必要があります。

マイナーバージョンは明示的にされておらず、安定したAPIエンドポイントを提供します。
新機能は同じバージョン番号のAPIに追加されます。
メジャーAPIバージョンの変更とAPIバージョン全体の削除は、GitLabのメジャーリリースと連動して行われます。
バージョン間のすべての非推奨と変更は、ドキュメントに記載されています。

以下は非推奨プロセスの対象外であり、予告なしにいつでも削除される可能性があります:

REST APIリソースで実験的またはベータとしてラベル付けされた要素。
機能フラグで制御されており、デフォルトで無効になっているフィールド。

GitLab Self-Managedの場合、EEインスタンスからCEインスタンスにダウングレードすると、破壊的な変更が発生します。