- 互換性ガイドライン
- APIの使い方
- 認証
- ステータスコード
- リダイレクト
- ページネーション
- パスパラメータ
- 名前空間パスエンコーディング
- ファイルパス、ブランチ、タグ名のエンコーディング
- リクエスト・ペイロード
-
arrayおよびhashタイプの API パラメータのエンコード id対iidnull対false- データ検証とエラー報告
- 不明なルート
+を ISO 8601 日付でエンコードします。- サードパーティクライアント
- レート制限
- コンテンツタイプ
- スパムとして検出されたリクエストの解決
REST API
REST API は、GraphQL API に比べて古くから存在しているため、開発者によってはなじみがあるかもしれません。伝統的なAPIアーキテクチャに慣れている開発者には、REST APIが適しています。
互換性ガイドライン
HTTP APIは、4 という1つの番号でバージョン管理されています。この番号は、SemVerで説明されているメジャーバージョン番号を象徴しています。このため、後方互換性のない変更には、このバージョン番号を変更する必要があります。
マイナーバージョンは明示されないため、安定したAPIエンドポイントを実現できます。同じバージョン番号のAPIに新機能を追加できます。
新機能やバグフィックスはGitLabと同時にリリースされます。偶発的なパッチやセキュリティのリリースを除けば、GitLabの新しいマイナーバージョンは毎月リリースされます。APIのメジャーバージョンの変更、API全体のバージョンの削除は、GitLabのメジャーリリースと同時に行われます。
すべての非推奨事項やバージョン間の変更はドキュメントに記載されています。
現在の状態
APIバージョンv4のみ利用可能です。
APIの使い方
APIリクエストには、api とAPIバージョンの両方を含める必要があります。API のバージョンはlib/api.rbで定義されています。例えば、v4 API のルートは/api/v4にあります。
有効なAPIリクエスト
以下は、架空のgitlab.example.com エンドポイントへのリクエストの基本的な例です：
curl "https://gitlab.example.com/api/v4/projects"
APIはJSONを使用してデータをシリアライズします。API URL の最後に.json を指定する必要はありません。
gitlab.example.com をgitlab.com に置き換えて GitLab.com (GitLab SaaS) にクエリします。認証が原因でアクセスが拒否されることがあります。詳細については、認証を参照してください。HTTPレスポンスヘッダを公開するAPIリクエスト
HTTP レスポンス・ヘッダを公開したい場合は、--include オプションを使用します：
curl --include "https://gitlab.example.com/api/v4/projects"
HTTP/2 200
...
このリクエストは予期しないレスポンスを調査するのに役立ちます。
終了コードを含むAPIリクエスト
HTTP 終了コードを公開したい場合は、--fail オプションを指定します：
curl --fail "https://gitlab.example.com/api/v4/does-not-exist"
curl: (22) The requested URL returned error: 404
HTTP 終了コードは、REST リクエストの成否を診断するのに役立ちます。
認証
ほとんどのAPIリクエストは認証を必要とするか、認証が提供されない場合にのみ公開データを返します。認証が不要な場合は、各エンドポイントのドキュメントにその旨が明記されています。たとえば、/projects/:id エンドポイント は認証を必要としません。
GitLab APIでは、いくつかの方法で認証を行うことができます：
プロジェクトアクセストークンは以下によってサポートされます：
- 自己管理型 GitLab：Free、Premium、Ultimate。
- GitLab SaaS：Premium と Ultimate。
あなたが管理者の場合、あなたやあなたのアプリケーションは特定のユーザーとして認証することができます。これを行うには、以下を使用します：
認証情報が有効でない、あるいは見つからない場合、GitLab はステータスコード401 のエラーメッセージを返します：
{
"message": "401 Unauthorized"
}
OAuth 2.0 トークン
OAuth 2.0トークンを使用して API を認証するには、access_token パラメータまたはAuthorization ヘッダを指定します。
OAuth 2.0 トークンをパラメータで使用する例：
curl "https://gitlab.example.com/api/v4/projects?access_token=OAUTH-TOKEN"
OAuth 2.0 トークンをヘッダで使用する例：
curl --header "Authorization: Bearer OAUTH-TOKEN" "https://gitlab.example.com/api/v4/projects"
OAuth2.0プロバイダとしてのGitLabについて、詳しくはこちらをご覧ください。
refresh_token パラメータを使ってトークンを更新することができます。リフレッシュトークンを使って新しいアクセストークンをリクエストする方法については、OAuth 2.0 トークンのドキュメントをご覧ください。個人/プロジェクト/グループアクセストークン
アクセストークンを使用して API を認証するには、private_token パラメータまたはPRIVATE-TOKEN ヘッダのいずれかに渡します。
個人、プロジェクト、グループのアクセストークンをパラメータで使用する例：
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はこのクッキーを認証に使用します。APIを使って新しいセッションクッキーを生成することはサポートされていません。
この認証方法の主なユーザーはGitLabのWebフロントエンド自身です。ウェブフロントエンドは、アクセストークンを明示的に渡さずにプロジェクトの一覧を取得するために、認証されたユーザーとして API を使うことができます。
なりすましトークン
なりすましトークンは、個人アクセストークンの一種です。管理者のみが作成でき、特定のユーザーとしてAPIを認証するために使用されます。
インパーソネーショントークンは、以下の代替手段として使用します：
- ユーザーのパスワードまたは個人アクセストークン。
- Sudo機能。ユーザーや管理者のパスワードやトークンはわからないかもしれませんし、時間の経過とともに変わるかもしれません。
詳しくはusers APIドキュメント を参照してください。
なりすましトークンは、通常の個人用アクセストークンとまったく同じように使われます。private_token パラメータかPRIVATE-TOKEN ヘッダで渡すことができます。
なりすましを無効にする
デフォルトでは、なりすましは有効になっています。なりすましを無効にするには
-
/etc/gitlab/gitlab.rbファイルを編集します：gitlab_rails['impersonation_enabled'] = false -
ファイルを保存し、変更を有効にするためにGitLabを再設定してください。
-
config/gitlab.ymlファイルを編集します：gitlab: impersonation_enabled: false -
ファイルを保存し、変更を有効にするためにGitLabを再起動してください。
なりすましを再び有効にするには、この設定を削除してGitLabを再設定するか（Linuxパッケージインストール）、GitLabを再起動します（セルフコンパイルインストール）。
Sudo
すべての API リクエストは、sudo スコープを持つ OAuth または個人アクセストークンで管理者として認証されていれば、他のユーザーであるかのように API リクエストを実行できます。APIリクエストは、なりすましたユーザーの権限で実行されます。
管理者として、sudo パラメータを渡すには、クエリ文字列を使用するか、オペレーションを実行したいユーザーの ID またはユーザー名 (大文字と小文字は区別されません) をヘッダとして渡します。ヘッダとして渡す場合、ヘッダ名はSudo でなければなりません。
管理者以外のアクセストークンが渡された場合、GitLabはステータスコード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 リクエストによるリクエストの例：
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 を、リソースの削除が予定されている場合は202 Accepted を返します。 |
以下の表は、APIリクエストで使用可能なリターンコードです。
| 戻り値 | 説明 |
|---|---|
200 OK |
GET,PUT またはDELETE リクエストが成功し、リソース自体が JSON として返されます。 |
201 Created |
POST リクエストは成功し、リソースは JSON として返されます。 |
202 Accepted |
GET 、PUT またはDELETE のリクエストは成功し、リソースは処理のためにスケジュールされました。 |
204 No Content | サーバーはリクエストに成功し、応答ペイロードボディに送信する追加コンテンツはありません。 |
301 Moved Permanently | リソースはLocation ヘッダで指定された URL に確定的に移動されました。 |
304 Not Modified | リソースは前回のリクエスト以降変更されていません。 |
400 Bad Request | APIリクエストの必須属性が欠落しています。例えば、イシューのタイトルが指定されていません。 |
401 Unauthorized | ユーザーが認証されていません。有効なユーザ・トークンが必要です。 |
403 Forbidden | リクエストが許可されていません。例えば、ユーザーはプロジェクトの削除を許可されていません。 |
404 Not Found | リソースにアクセスできませんでした。たとえば、リソースの ID が見つからないか、ユーザーにリソースへのアクセス権限がない場合です。 |
405 Method Not Allowed | リクエストがサポートされていません。 |
409 Conflict | 競合するリソースがすでに存在します。例えば、既に存在する名前でプロジェクトを作成する場合。 |
412 Precondition Failed | リクエストは拒否されました。リソースを削除しようとしたときにIf-Unmodified-Since ヘッダが提供され、その間に変更された場合に発生する可能性があります。 |
422 Unprocessable | エンティティを処理できませんでした。 |
429 Too Many Requests | ユーザーがアプリケーションレートの制限を超えました。 |
500 Server Error | リクエストの処理中にサーバーで異常が発生しました。 |
503 Service Unavailable | サーバが一時的に過負荷のため、リクエストを処理できません。 |
リダイレクト
GitLab 16.4 で
api_redirect_moved_projectsというフラグで導入されました。デフォルトでは無効になっています。
フラグ: GitLab.comでは、この機能は利用できません。セルフマネジメントのGitLabでは、デフォルトではこの機能は利用できません。利用可能にするには、管理者がapi_redirect_moved_projectsという機能フラグを有効にします。
REST APIはリダイレクトで応答することができ、ユーザーはそのような応答を処理できなければなりません。ユーザーはリダイレクトに従って、Location ヘッダーで指定された URI へのリクエストを繰り返す必要があります。
プロジェクトが別のパスに移動した例：
curl --verbose "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は以下のページネーション方法をサポートしています：
- オフセットベースのページ分割。デフォルトの方法で、すべてのエンドポイントで利用可能です。
- キーセットベースのページ分割。一部のエンドポイントに追加されましたが、順次ロールアウトされます。
大規模なコレクションでは、パフォーマンス上の理由から、オフセットによるページネーションではなく、キーセットによるページネーション (利用可能な場合) を使用すべきです。
オフセットベースのページ処理
返された結果が多くのページにまたがることがあります。リソースを一覧表示する際に、以下のパラメータを渡すことができます：
| パラメータ | 説明 |
|---|---|
page | ページ番号 (デフォルト:1)。 |
per_page | ページあたりのリスト項目数 (デフォルト:20 、最大:100)。 |
以下の例では、1 ページにつき 50 のネームスペースをリストします：
curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/namespaces?per_page=50"
ページネーションLink ヘッダー
Link ヘッダ は各レスポンスで返されます。これらはrel がprev,next,first, またはlast に設定され、関連する URL をコンテナとして持っています。独自のURLを生成する代わりに、必ずこれらのリンクを使用してください。
GitLab.comユーザーの場合、一部のページネーションヘッダが返されないことがあります。
次の cURL の例では、出力を一ページあたり三件 (per_page=3) に制限し、ID9のプロジェクトに属する ID8 のイシューのコメントの二ページ目 (page=2) を要求しています：
curl --head --header "PRIVATE-TOKEN: <your_access_token>" "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 | yes |
keyset (キーセットのページ分割を有効にします)。 |
per_page | いいえ | ページあたりのリスト項目数 (デフォルト:20 、最大:100)。 |
order_by | yes | 並び順を指定する列。 |
sort | yes | ソート順 (asc またはdesc) |
次の例では、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
...
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>" "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 オプションに依存し、複数の追加フィルタを持つことができます。
Link 仕様Linkに合わせるため、GitLab 14.0ではLinks ヘッダが削除されました。Link この Linkヘッダーは](https://www.w3.org/wiki/LinkHeader)GitLab 13.1で追加さ](https://www.w3.org/wiki/LinkHeader)れたもので、代わりに使うべきです。コレクションの末尾に到達し、さらに取得するレコードがない場合、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 のみ | 認証済みユーザーと未認証ユーザー |
ページネーションのレスポンスヘッダ
パフォーマンス上の理由から、クエリが10,000以上のレコードを返す場合、GitLabは以下のヘッダを返しません：
-
x-total. -
x-total-pages. -
rel="last"link
パスパラメータ
エンドポイントにパス・パラメータがある場合、ドキュメントではその前にコロンを付けて表示します。
使用例：
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か、プロジェクトの設定の「General > Advanced > Change path」で確認できます。
ファイルパス、ブランチ、タグ名のエンコーディング
ファイルパス、ブランチ、タグに/ が含まれている場合は、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[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"} ] }' \
"https://gitlab.example.com/api/v4/projects/169/pipeline"
id 対iid
リソースの中には、同じような名前のフィールドを2つ持つものがあります。例えば、イシュー、マージリクエスト、プロジェクトのマイルストーンなどです。これらのフィールドは
-
id:すべてのプロジェクトで一意であるID。 -
iid:追加の内部ID (ウェブUIに表示されます) : 1つのプロジェクトの範囲で一意です。
リソースがiid フィールドとid フィールドの両方を持つ場合、リソースをフェッチするには通常id の代わりにiid フィールドが使用されます。
例えば、id: 42 を持つプロジェクトに、id: 46 とiid: 5 を持つイシューがあるとします。 この場合：
- イシューを取得するための有効なAPIリクエストは
GET /projects/42/issues/5です。 - イシューを取得するための無効なAPIリクエストは
GET /projects/42/issues/46です。
このiid フィールドを iid持つすべてのリソースが.NETiid Frameworkによって取得さ iidれるわけではありません。どのフィールドを使用するかについては、特定のリソースのドキュメントを参照してください。
null 対false
API レスポンスでは、いくつかのブーリアン・フィールドがnull 値を null持つことができます。booleannull は nullデフォルト値を持たず、true でもfalse でもありません。GitLab は boolean フィールドのnull 値をfalseと同じように扱います。
boolean 引数では、true またはfalse の値のみを設定する必要があります（null は設定しないでください）。
データ検証とエラー報告
APIを使用する際、バリデーションエラーに遭遇することがあります。この場合、APIはHTTP400 エラーを返します。
このようなエラーは次のような場合に発生します：
- 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 日付でエンコードします。
クエリパラメータに+ を含める必要がある場合は、%2B を代わりに使用する必要があるかもしれません。W3 の勧告によると、+ はスペースとして解釈されてしまうからです。たとえば、ISO 8601 形式の日付に特定の時刻を含めたい場合、次のようにします：
2017-10-17T23:11:13.000+05:30
クエリパラメータの正しいエンコーディングは次のようになります：
2017-10-17T23:11:13.000%2B05:30
サードパーティクライアント
サードパーティのAPIクライアントライブラリをGitLabとインテグレーションすることができます。以下のライブラリはコミュニティメンバーによってメンテナーされており、GitLabは公式にサポートしていません。バグや機能提案はそれぞれのプロジェクトに報告してください。
これらのインテグレーションに関する質問は、GitLabコミュニティフォーラムをご利用ください。
C#
Go
ハスケル
Java
Node.js
Perl
PHP
Python
Ruby
Swift
レート制限
レートリミットの設定に関する管理者のドキュメントは、レートリミットをご覧ください。GitLab.comで特に使用される設定を見つけるには、GitLab.com-specific rate limitsをご覧ください。
コンテンツタイプ
GitLab API はデフォルトでapplication/json コンテントタイプをサポートしていますが、一部の API エンドポイントではtext/plain もサポートしています。
GitLab 13.10以降では、明示的にドキュメント化されていない限り、APIエンドポイントはデフォルトでtext/plain 。
スパムとして検出されたリクエストの解決
GitLab 14.9で導入されました。
REST APIリクエストがスパムとして検出されることがあります。リクエストがスパムとして検出され
-
CAPTCHA サービスが設定されていない場合、エラー応答が返されます。例えば
{"message":{"error":"Your snippet has been recognized as spam and has been discarded."}} - CAPTCHA サービスが設定されている場合、次のような応答が返されます：
-
needs_captcha_responseをtrueに設定してください。 -
spam_log_idとcaptcha_site_keyフィールドのセット。
使用例：
{"needs_captcha_response":true,"spam_log_id":42,"captcha_site_key":"REDACTED","message":{"error":"Your snippet has been recognized as spam. Please, change the content or solve the reCAPTCHA to proceed."}} -
-
captcha_site_keyを使用して、適切な CAPTCHA API を使用して CAPTCHA レスポンス値を取得します。Google reCAPTCHA v2のみサポートしています。 -
X-GitLab-Captcha-ResponseとX-GitLab-Spam-Log-Idヘッダを設定してリクエストを再送信してください。
export CAPTCHA_RESPONSE="<CAPTCHA response obtained from CAPTCHA service>"
export SPAM_LOG_ID="<spam_log_id obtained from initial REST response>"
curl --request POST --header "PRIVATE-TOKEN: $PRIVATE_TOKEN" --header "X-GitLab-Captcha-Response: $CAPTCHA_RESPONSE" --header "X-GitLab-Spam-Log-Id: $SPAM_LOG_ID" "https://gitlab.example.com/api/v4/snippets?title=Title&file_name=FileName&content=Content&visibility=public"