APIドキュメント

シンプルでパワフルなAPIでGitLabを自動化。

GitLabのメインAPIはRESTAPIです。 したがって、このセクションのドキュメントはRESTの概念の知識を前提としています。

利用可能なAPIリソース

利用可能なリソースとそのエンドポイントのリストについては、APIリソースを参照してください。

SCIM

GitLab.com Silver 以上は、RFC7644 プロトコルを実装し、/Users エンドポイントを提供するSCIM API を提供します。ベース URL は/api/scim/v2/groups/:group_path/Users/です。

GraphQLへの道

GitLabでGraphQLが利用できるようになり、コントローラ固有のエンドポイントを廃止することができるようになります。

GraphQLには多くの利点があります：

  1. 2つの異なるAPIをメンテナーする必要はありません。
  2. APIの呼び出し側は、必要なものだけを要求できます。
  3. デフォルトでバージョン管理されています。

これは現在のv4 REST APIと共存するものです。 もしv5 APIがあれば、これはGraphQLの上の互換レイヤーになるはずです。

GraphQLには特許やライセンスに関する懸念がありましたが、リファレンス実装をMITの下で再ライセンスし、GraphQL仕様にOWFライセンスを使用することで、私たちが満足するまでに解決されました。

互換性ガイドライン

HTTP APIは1つの番号を使用してバージョン管理され、現在の番号は4です。 この番号は、SemVerで説明されているメジャーバージョン番号と同じものを表します。 つまり、後方互換性のない変更には、このバージョン番号を変更する必要があります。 ただし、マイナーバージョンは明示されません。 これにより、安定したAPIエンドポイントを提供できるだけでなく、同じバージョン番号でAPIに新機能を追加できます。

新機能やバグフィックスは新しいGitLabと同時にリリースされ、付随的なパッチやセキュリティリリースを除けば、毎月22日にリリースされます。 後方互換性のない変更（エンドポイントの削除、パラメータの削除など）やAPIバージョン全体の削除は、GitLab自体のメジャーポイントリリースと同時に行われます。 2つのバージョン間のすべての非推奨事項や変更点は、ドキュメントに記載されています。 v3とv4の間の変更点については、v3からv4のドキュメントをお読みください。

現状

現在、APIバージョンv4のみが利用可能です。 バージョンv3はGitLab 11.0で削除されました。

基本的な使い方

APIリクエストの前には、api とAPIバージョンを付ける必要があります。 APIバージョンはlib/api.rbで定義されています。例えば、v4 API のルートは/api/v4にあります。

cURLを使用した有効なAPIリクエストの例： 

curl "https://gitlab.example.com/api/v4/projects"

APIはJSONを使用してデータをシリアライズします。 API URLの末尾に.json を指定する必要はありません。

認証

ほとんどのAPIリクエストは認証を必要とするか、認証が提供されない場合にのみ公開データを返します。 認証が不要な場合については、各エンドポイントのドキュメントに記載されています。 例えば、/projects/:id エンドポイント。

GitLab API の認証にはいくつかの方法があります：

  1. OAuth2 トークン
  2. 個人アクセストークン
  3. プロジェクトアクセストークン
  4. セッションクッキー
  5. GitLab CI/CDジョブトークン (特定のエンドポイントのみ）

特定のユーザーとしてAPI認証を行いたい、あるいはそのようなアプリケーションやスクリプトを作りたい管理者のために、2つのオプションが用意されています：

  1. なりすましトークン
  2. 須藤

認証情報が無効または省略された場合は、ステータスコード401でエラーメッセージが返されます： 

{
  "message": "401 Unauthorized"
}

OAuth2 トークン

OAuth2 トークンを使用して API を認証するには、access_token パラメータまたはAuthorization ヘッダのいずれかにトークンを渡します。

OAuth2 トークンをパラメータで使用する例： 

curl "https://gitlab.example.com/api/v4/projects?access_token=OAUTH-TOKEN"

OAuth2 トークンをヘッダで使用する例： 

curl --header "Authorization: Bearer OAUTH-TOKEN" "https://gitlab.example.com/api/v4/projects"

OAuth2プロバイダーとしてのGitLabについて、詳しくはこちらをご覧ください。

個人/プロジェクトアクセストークン

アクセストークンは、private_token パラメータまたはPrivate-Token ヘッダのいずれかに渡すことで、API での認証に使用できます。

個人/プロジェクトアクセストークンをパラメータで使用する例： 

curl "https://gitlab.example.com/api/v4/projects?private_token=<your_access_token>"

個人/プロジェクトアクセストークンをヘッダーで使用する例： 

curl --header "Private-Token: <your_access_token>" "https://gitlab.example.com/api/v4/projects"

OAuth準拠のヘッダを持つ個人/プロジェクトアクセストークンを使用することもできます： 

curl --header "Authorization: Bearer <your_access_token>" "https://gitlab.example.com/api/v4/projects"

GitLabのメインアプリケーションにサインインすると、_gitlab_session Cookieが設定されます。APIはこのCookieがあれば認証のために使いますが、APIを使って新しいセッションCookieを生成することは現在サポートされていません。

この認証方式の主な利用者は GitLab のウェブフロントエンドで、アクセストークンを明示的に渡さなくても、認証済みユーザーとして API を使ってプロジェクトの一覧などを取得することができます。

GitLab CI ジョブトークン

いくつかのAPIエンドポイントを使えば、GitLab CI/CDジョブトークンを使ってAPI認証を行うことができます：

なりすましトークン

GitLab 9.0 で導入されました。管理者権限が必要です。

インパーソネーショントークンは、管理者のみが特定のユーザーに対して作成できるパーソナルアクセストークンの一種です。 特定のユーザーとしてAPI認証を行うアプリケーションやスクリプトを構築したい場合に最適です。

ユーザのパスワードや個人アクセストークンを直接使う方法や、Sudo機能を使う方法の代替です。

詳細については、ユーザーAPIのドキュメントを参照してください。

なりすましトークンは、通常の個人アクセストークンとまったく同じように使用され、private_token パラメータまたはPrivate-Token ヘッダのいずれかで渡すことができます。

なりすましの無効化

GitLab 11.6から導入されました。

デフォルトでは、なりすましは有効になっています。 なりすましを無効にするには、次のようにします：

オムニバス・インストール用

  1. /etc/gitlab/gitlab.rbを編集します： 

    gitlab_rails['impersonation_enabled'] = false

  2. ファイルを保存し、変更を有効にするために GitLab を再設定します。

なりすましを再び有効にするには、この設定を削除して GitLab を再設定してください。

ソースからのインストールの場合

  1. config/gitlab.ymlを編集します： 

    gitlab:
  impersonation_enabled: false

  2. ファイルを保存し、GitLabを再起動して変更を有効にします。

なりすましを再び有効にするには、この設定を削除して GitLab を再起動します。

須藤

注：管理者のみが利用できます。

すべての API リクエストは、sudo スコープを持つ OAuth またはパーソナルアクセストークンで管理者として認証されている場合、他のユーザーであるかのように API コールを実行できます。

sudo パラメータには、クエリ文字列か、オペレーションを実行したいユーザのID/ユーザ名をヘッダとして渡す必要があります。 ヘッダとして渡す場合、ヘッダ名はSudoでなければなりません。

注意：ユーザー名は大文字と小文字を区別しません。

管理者以外のアクセストークンが提供された場合、エラーメッセージがステータスコード403で返されます： 

{
  "message": "403 Forbidden - Must be admin to use sudo"
}

sudo スコープを持たないアクセストークンが提供された場合、エラーメッセージがステータスコード403で返されます： 

{
  "error": "insufficient_scope",
  "error_description": "The request requires higher privileges than provided by the access token.",
  "scope": "sudo"
}

sudo ユーザ ID またはユーザ名が見つからない場合、エラーメッセージがステータスコード404で返されます： 

{
  "message": "404 User with ID or username '123' Not Found"
}

有効なAPIコールと、ユーザー名を指定してsudoリクエストでcURLを使用したリクエストの例： 

GET /projects?private_token=<your_access_token>&sudo=username

curl --header "Private-Token: <your_access_token>" --header "Sudo: username" "https://gitlab.example.com/api/v4/projects"

有効なAPIコールと、cURLを使用したsudoリクエスト、IDを指定したリクエストの例： 

GET /projects?private_token=<your_access_token>&sudo=23

curl --header "Private-Token: <your_access_token>" --header "Sudo: 23" "https://gitlab.example.com/api/v4/projects"

ステータスコード

APIは、コンテキストとアクションに応じて異なるステータスコードを返すように設計されています。 これにより、リクエストがエラーになった場合、呼び出し元は何が問題だったのかをインサイトで知ることができます。

以下の表は、API関数の一般的な動作の概要です。

リクエストタイプ 説明
GET 1つ以上のリソースにアクセスし、その結果をJSONとして返します。
POST リソースの作成に成功した場合は201 Created を返し、新しく作成されたリソースを JSON として返します。
GET /PUT リソースへのアクセスや変更が成功した場合は200 OK を返します。（変更された）結果は JSON として返されます。
DELETE リソースの削除に成功した場合は204 No Content を返します。

次の表は、APIリクエストで返される可能性のあるコードを示しています。

戻り値 説明
200 OK GET,PUT またはDELETE リクエストが成功すると、リソースそのものが JSON として返されます。
204 No Content サーバーがリクエストに成功し、レスポンスペイロードボディに送るべき追加コンテンツがないこと。
201 Created POST リクエストは成功し、リソースは JSON として返されます。
304 Not Modified 最後のリクエスト以降、リソースが変更されていないことを示します。
400 Bad Request イシューのタイトルが指定されていないなど、APIリクエストの必須属性が欠落しています。
401 Unauthorized ユーザーが認証されていないため、有効なユーザートークンが必要です。
403 Forbidden リクエストは許可されていません。例えば、ユーザーはプロジェクトの削除を許可されていません。
404 Not Found リソースにアクセスできませんでした。例えば、リソースのIDが見つかりませんでした。
405 Method Not Allowed リクエストはサポートされていません。
409 Conflict すでに存在する名前でプロジェクトを作成するなど、競合するリソースがすでに存在する場合。
412 リクエストが拒否されたことを示します。 リソースを削除しようとしたときにIf-Unmodified-Since ヘッダが提供され、 そのヘッダが途中で変更された場合に発生する可能性があります。
422 Unprocessable エンティティを処理できませんでした。
500 Server Error リクエストの処理中にサーバー側で何か問題が発生しました。

ページネーション

2種類のページネーション方法をサポートしています：

  • オフセット・ベースのページネーション。 これはデフォルトの方法で、すべてのエンドポイントで利用可能です。
  • キーセットベースのページネーション。 一部のエンドポイントに追加されましたが、順次ロールアウトされます。

大規模なコレクションでは、パフォーマンス上の理由から、オフセット・ページネーションよりもキーセット・ページネーション（利用可能な場合）をお勧めします。

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

返される結果が多くのページにまたがることもあります。 リソースを一覧表示する際には、以下のパラメータを渡すことができます：

パラメータ 説明
page ページ番号 (デフォルト:1)
per_page 1ページに表示する項目数 (デフォルト:20, 最大:100)

以下の例では、1 ページあたり 50 のネームスペースをリストしています。 

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

リンクヘッダは各レスポンスと一緒に送り返されます。リンクヘッダにはrel が設定され、prev/next/first/last に関連する URL が含まれています。独自の URL を生成する代わりに、これらのリンクを使用してください。

以下のcURLの例では、1ページ(per_page=3)あたりの出力を3件に制限し、IDが8.のプロジェクトに属する 8IDが8. 8のイシューのコメントの2ページ目(page=2)を要求しています： 

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

すると、こう返されます： 

HTTP/1.1 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

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

追加のページネーションヘッダーも送り返されます。

ヘッダー 説明
X-Total アイテムの総数
X-Total-Pages 総ページ数
X-Per-Page ページあたりの項目数
X-Page 現在のページのインデックス(1から始まる)
X-Next-Page 次ページのインデックス
X-Prev-Page 前のページのインデックス
注意:GitLab 11.8以降のパフォーマンス上の理由から、api_kaminari_count_with_limit機能フラグの背後にある**、リソースの数が 10,000 以上の場合、X-Total とX-Total-Pages ヘッダだけでなく、rel="last" Link もレスポンスヘッダに存在しません。

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

キーセットページネーションは、より効率的なPagesの検索を可能にし、オフセットベースのページネーションとは対照的に、ランタイムはコレクションのサイズに依存しません。

この方法は、以下のパラメータによって制御されます：

パラメータ 説明
pagination keyset (キーセットのページネーションを有効にするため)
per_page 1ページに表示する項目数 (デフォルト:20, 最大:100)

以下の例では、1ページに50のプロジェクトを id 、昇順に並べています。 

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

レスポンス・ヘッダには、次のページへのリンクが含まれています。 たとえば、以下のようなものです： 

HTTP/1.1 200 OK
...
Links: <https://gitlab.example.com/api/v4/projects?pagination=keyset&per_page=50&order_by=id&sort=asc&id_after=42>; rel="next"
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
...
非推奨:W3C仕様に合わせるため、GitLab 14.0ではLinks ヘッダが削除されます。

次のページへのリンクには、すでに検索したレコードを除外する追加フィルタid_after=42 が含まれています。フィルタの種類は、使用するorder_by オプションによって異なり、複数の追加フィルタがある可能性があることに注意してください。

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

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

キーセットベースのページネーションは、選択されたリソースと順序オプションでのみサポートされています：

リソース ご注文
プロジェクト order_by=id ただ

パスパラメータ

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

使用例： 

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>" "https://gitlab.example.com/api/v4/projects/5/share/17"
注意:URLエンコードが必要なパス・パラメータは、それに従わなければなりません。 そうでない場合、APIエンドポイントにマッチせず、404で応答します。 APIの前に何か（例えばApache）がある場合、それがURLエンコードされたパス・パラメータをデコードしないようにしてください。

名前空間付きパスエンコーディング

名前空間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

リクエスト・ペイロード

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

  • クエリー文字列： 

     curl --request POST "https://gitlab/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/api/v4/projects"

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

array およびhash 型の API パラメータのエンコード

以下のように、array とhash タイプのパラメータを指定して API を呼び出すことができます：

array

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

curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
-d "import_sources[]=github" \
-d "import_sources[]=bitbucket" \
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" \
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>" \
"https://gitlab.example.com/api/v4/projects/169/pipeline?ref=master&variables[][key]=VAR1&variables[][value]=hello&variables[][key]=VAR2&variables[][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"} ] }' \
"https://gitlab.example.com/api/v4/projects/169/pipeline"

id 対iid

例えば、イシュー、マージリクエスト、プロジェクトのマイルストーンなどです。 これらのフィールドは以下のとおりです：

  • idIDはすべてのプロジェクトで一意です。
  • iid: 1つのプロジェクトの範囲内でユニークな、追加の内部ID。
注：** はウェブ 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持つすべてのリソースがiid.NET によって取得さ iidれるわけではありません。 どのフィールドを使用するかについては、特定のリソースのドキュメントを参照してください。

データ検証とエラーレポーター

APIを使用する際、バリデーションエラーに遭遇することがあります。その場合、APIはHTTP400 ステータスを返します。

このようなエラーは2つのケースで発生します：

  • APIリクエストの必須属性が欠落しています（イシューのタイトルが指定されていないなど）。
  • 属性がバリデーションに合格しなかった場合（例：ユーザー経歴が長すぎるなど

属性が欠落している場合は、次のようになります： 

HTTP/1.1 400 Bad Request
Content-Type: application/json
{
    "message":"400 (Bad request) \"title\" not given"
}

バリデーションエラーが発生すると、エラーメッセージが異なります。 エラーメッセージには、バリデーションエラーの詳細がすべて記録されます： 

HTTP/1.1 400 Bad Request
Content-Type: application/json
{
    "message": {
        "bio": [
            "is too long (maximum is 255 characters)"
        ]
    }
}

エラーメッセージのフォーマットは以下の通りです： 

{
    "message": {
        "<property-name>": [
            "<error-message>",
            "<error-message>",
            ...
        ],
        "<embed-entity>": {
            "<property-name>": [
                "<error-message>",
                "<error-message>",
                ...
            ],
        }
    }
}

ルート不明

存在しないAPI URLにアクセスしようとすると、404 Not Foundが表示されます。 

HTTP/1.1 404 Not Found
Content-Type: application/json
{
    "error": "404 Not Found"
}

ISO 8601 日付の+ のエンコード

クエリパラメータに+ を含める必要がある場合、+ をスペースとして解釈してしまうW3 の勧告により、代わりに%2B を使用する必要があるかもしれません。 たとえば、ISO 8601 の日付で、次のように山岳標準時の時刻を渡したい場合があります： 

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

クエリーパラメーターの正しいエンコーディングは次のようになります： 

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

クライアント

一般的なプログラミング言語用の非公式なGitLab APIクライアントがたくさんあります。GitLabのウェブサイトで完全なリストをご覧ください。

レート制限

レートリミットの設定に関する管理者のドキュメントは、レートリミットを参照してください。 GitLab.comで特に使用される設定を見つけるには、GitLab.com固有のレートリミットを参照してください。