• 호환성 가이드라인
  • 현재 상태
• API 사용 방법
  • 유효한 API 요청
  • HTTP 응답 헤더를 노출하는 API 요청
  • 종료 코드를 포함하는 API 요청
• 인증
  • OAuth 2.0 토큰
  • 개인/프로젝트/그룹 액세스 토큰
  • 작업 토큰
  • 세션 쿠키
  • 가장하기 토큰
    • 가장하기 비활성화
  • Sudo
• 상태 코드
• 리다이렉트
• 페이지네이션
  • 오프셋 기반 페이징
    • 페이징 Link 헤더
    • 기타 페이징 헤더
  • 키셋 기반 페이징
    • 지원되는 리소스
  • 페이지네이션 응답 헤더
• 경로 매개변수
• 네임스페이스 경로 인코딩
• 파일 경로, 브랜치 및 태그 이름 인코딩
• 요청 페이로드
• array 및 hash 유형의 인코딩 API 매개변수
  • array
  • hash
  • 해시의 배열
• id vs iid
• null vs false
• 데이터 유효성 검사 및 오류 보고
• 알 수 없는 경로
• ISO 8601 날짜에서 + 인코딩
• 제3자 클라이언트
  • C#
  • Go
  • Haskell
  • Java
  • Node.js
  • Perl
  • PHP
  • Python
  • Ruby
  • Rust
  • Swift
• 요청 제한
• 콘텐츠 유형
• 스팸으로 감지된 요청 해결

REST API

세부사항: Tier: Free, Premium, Ultimate 제공: GitLab.com, Self-managed, GitLab Dedicated

REST API는 GraphQL API보다 오래된 만큼, 일부 개발자에게 더 익숙할 수 있습니다. 전통적인 API 아키텍처에 익숙한 개발자에게 좋은 선택이 될 수 있습니다.

호환성 가이드라인

HTTP API는 단일 번호인 4로 버전이 지정됩니다. 이 번호는 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을 명시할 필요는 없습니다.

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는 여러 가지 방법으로 인증할 수 있습니다:

• OAuth 2.0 토큰
• 개인 접근 토큰
• 프로젝트 접근 토큰
• 그룹 접근 토큰
• 세션 쿠키
• GitLab CI/CD 작업 토큰 (특정 엔드포인트 전용)

프로젝트 접근 토큰은 다음을 지원합니다:

• Self-managed GitLab: Free, Premium, Ultimate.
• GitLab SaaS: Premium, Ultimate.

관리자인 경우, 특정 사용자로 인증하거나 애플리케이션을 통해 인증할 수 있습니다. 이를 위해 다음을 사용합니다:

• 임퍼스네이션 토큰
• Sudo

인증 정보가 유효하지 않거나 누락된 경우, GitLab은 401 상태 코드와 함께 오류 메시지를 반환합니다:

{
  "message": "401 Unauthorized"
}

OAuth 2.0 토큰

OAuth 2.0 토큰을 사용하여 access_token 매개변수 또는 Authorization 헤더에 전달하여 API에 인증할 수 있습니다.

매개변수에서 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"

GitLab을 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"

작업 토큰

작업 토큰은 job_token 매개변수 또는 JOB-TOKEN 헤더에 토큰을 전달하여 특정 API 엔드포인트와 인증하는 데 사용할 수 있습니다. GitLab CI/CD 작업에서 토큰을 전달하기 위해 CI_JOB_TOKEN 변수를 사용합니다.

매개변수에서 작업 토큰을 사용하는 예시:

curl --location --output artifacts.zip "https://gitlab.example.com/api/v4/projects/1/jobs/42/artifacts?job_token=$CI_JOB_TOKEN"

헤더에서 작업 토큰을 사용하는 예시:

curl --header "JOB-TOKEN:$CI_JOB_TOKEN" "https://gitlab.example.com/api/v4/projects/1/releases"

세션 쿠키

기본 GitLab 애플리케이션에 로그인하면 _gitlab_session 쿠키가 설정됩니다. API는 이 쿠키를 사용하여 인증합니다. API를 사용하여 새 세션 쿠키를 생성하는 것은 지원되지 않습니다.

이 인증 방법의 주요 사용자는 GitLab 자체의 웹 프론트엔드입니다. 웹 프론트엔드는 액세스 토큰을 명시적으로 전달하지 않고 인증된 사용자로 API를 사용하여 프로젝트 디렉터리을 얻을 수 있습니다.

가장하기 토큰

가장하기 토큰은 관리자만이 생성할 수 있는 개인 액세스 토큰의 유형입니다. 이 토큰은 특정 사용자로서 API로 인증하도록 사용되며, 다음을 대체하는 대안으로 사용됩니다:

• 사용자의 암호 또는 개인 액세스 토큰 중 하나.
• Sudo 기능. 사용자 또는 관리자의 암호 또는 토큰이 알려지지 않았거나 시간이 지나면 변경될 수 있습니다.

자세한 정보는 사용자 API 문서를 참조하십시오.

가장하기 토큰은 일반적인 개인 액세스 토큰과 정확히 동일하게 사용되며, private_token 매개변수 또는 PRIVATE-TOKEN 헤더에 전달할 수 있습니다.

가장하기 비활성화

기본적으로 가장하기가 활성화되어 있습니다. 가장하기를 비활성화하려면:

가장하기를 다시 활성화하려면 이 구성을 제거하고 GitLab을 재구성(Linux 패키지 설치)하거나 GitLab을 다시 시작(자체 컴파일 설치)하십시오.

Sudo

모든 API 요청은 sudo 범위가 있는 OAuth 또는 개인 액세스 토큰으로 관리자로 인증된 상태에서 다른 사용자처럼 API 요청을 수행하는 것을 지원합니다. API 요청은 가장하기 사용자의 권한으로 실행됩니다.

관리자로서는 쿼리 문자열 또는 사용자의 ID 또는 사용자 이름(대소문자를 구분하지 않음)을 사용하여 sudo 매개변수를 전달합니다. 헤더로 전달하면 헤더 이름은 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"
}

가장하기 사용자 ID 또는 사용자 이름을 찾을 수 없는 경우 상태 코드가 404인 오류 메시지가 반환됩니다:

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

유효한 API 요청 및 cURL을 사용한 가장하기 요청 예시를 보여줍니다. 여기에 사용자 이름을 제공하여 cURL을 사용한 유효한 API 요청과 가장하기 요청이 포함됩니다:

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을 사용한 가장하기 요청의 또 다른 예시를 보여줍니다. 여기에 ID를 제공하여 cURL을 사용한 유효한 API 요청과 가장하기 요청이 포함됩니다:

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 기능이 일반적으로 어떻게 작동하는지에 대한 개요를 제공합니다.

다음 표는 API 요청에 대한 가능한 반환 코드를 보여줍니다.

리다이렉트

• GitLab 16.4에서 플래그인 api_redirect_moved_projects와 함께 도입되었습니다. 기본값으로 비활성화되어 있습니다.
• GitLab 16.7에서 일반적으로 사용 가능해졌습니다. 피처 플래그 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
...
이 리소스는 영구적으로 https://gitlab.example.com/api/v4/projects/81로 이동되었습니다.

페이지네이션

GitLab은 다음과 같은 페이지네이션 방법을 지원합니다.

• 오프셋 기반 페이지네이션. 기본 방법으로 모든 엔드포인트에서 사용 가능합니다. 그러나 users 엔드포인트를 제외하고 GitLab 16.5 이상에서 사용 가능합니다.
• Keyset 기반 페이지네이션. 일부 엔드포인트에 추가되었으며 점진적으로 전개 중입니다.

대량 컬렉션의 경우 성능상의 이유로 오프셋 페이지네이션 대신 (사용 가능한 경우) 키셋 페이지네이션을 사용해야 합니다.

오프셋 기반 페이징

• users 엔드포인트는 버전이 삭제되었습니다 GitLab 16.5 에서 오프셋 기반 페이징에 대해 계획되었으며 17.0에서 제거 예정입니다. 이 변경 사항은 파괴적인 변경입니다. 이 엔드포인트에는 대신 키셋 기반 페이징을 사용하세요.

때때로 반환된 결과물은 여러 페이지에 걸쳐 있을 수 있습니다. 자원을 나열할 때 다음 매개변수를 전달할 수 있습니다:

다음 예에서는 페이지당 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), 이슈 ID가 8인 프로젝트의 (8) 노트의 두 번째 페이지를 요청합니다 (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은 다음과 같은 추가 페이징 헤더도 반환합니다:

GitLab.com 사용자의 경우, 일부 페이징 헤더가 반환되지 않을 수 있습니다.

키셋 기반 페이징

키셋 기반 페이징은 페이지를 보다 효율적으로 검색할 수 있도록 하며 - 오프셋 기반 페이징과는 달리 - 런타임은 컬렉션 크기에 독립적입니다.

이 방법은 다음 파라미터로 제어됩니다. order_by 및 sort는 둘 다 필수입니다.

다음 예에서는 id를 오름차순으로 정렬하여 페이지당 50 프로젝트를 나열합니다:

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가 포함됩니다.

또 다른 예로, 다음 요청은 키셋 페이지 처리를 사용하여 name을 오름차순으로 정렬하여 페이지당 50 그룹을 나열합니다:

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 헤더가 없으며 결과 배열이 비어 있습니다.

당신은 본인의 URL을 작성하는 대신 주어진 링크만 사용하여 다음 페이지를 검색해야 합니다. 표시된 헤더 이외의 페이징 헤더는 노출되지 않습니다.

지원되는 리소스

키셋 기반 페이지네이션은 선택된 리소스 및 정렬 옵션에 대해서만 지원됩니다.

페이지네이션 응답 헤더

성능상의 이유로 쿼리가 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를 응답합니다. (예: 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는 해시 키/값 쌍을 포함하는 array 유형의 매개변수입니다 [{ 'key': 'UPLOAD_TO_S3', 'value': 'true' }]:

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 vs iid

일부 리소스에는 두 가지 유사한 이름의 필드가 있습니다. 예를 들어, 이슈, Merge Request 및 프로젝트 마일스톤입니다. 필드는 다음과 같습니다:

• id: 모든 프로젝트에서 고유한 ID입니다.
• iid: 단일 프로젝트 범위 내에서 고유한, 내부 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로 가져와지는 것은 아닙니다. 어떤 필드를 사용해야 하는지에 대한 지침은 특정 리소스의 문서를 참조하세요.

null vs false

API 응답에서 일부 부울 필드는 null 값을 가질 수 있습니다. null 부울은 기본 값이 없으며 true도 false도 아닙니다. GitLab은 부울 필드의 null 값을 false와 같이 취급합니다.

부울 인수에서는 null 대신 true 또는 false 값을 설정해야 합니다.

데이터 유효성 검사 및 오류 보고

API를 사용할 때 유효성 검사 오류를 만날 수 있습니다. 이 경우 API는 HTTP 400 오류를 반환합니다.

이러한 오류는 다음과 같은 경우에 발생합니다:

• 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

제3자 클라이언트

제3자 API 클라이언트 라이브러리를 GitLab과 통합할 수 있습니다. 다음 라이브러리들은 커뮤니티 회원에 의해 유지되며 GitLab에서 공식적으로 지원되지는 않습니다. 버그 및 기능 제안은 각 프로젝트에 보고하십시오.

이 통합들에 대한 질문이 있다면 GitLab 커뮤니티 포럼을 사용하세요.

C#

• GitLabApiClient
• NGitLab

Go

• go-gitlab

Haskell

• gitlab-haskell

Java

• gitlab4j-api
• java-gitlab-api

Node.js

• gitlab-yaac
• backbone-gitlab

Perl

• GitLab::API::v4

PHP

• php-gitlab-api

Python

• python-gitlab
  • 블로그 포스트: 효율적인 DevSecOps 워크플로: 실용적인 python-gitlab API 자동화
• libsaas_gitlab

Ruby

• GitLab REST API용 Ruby 래퍼 및 CLI

Rust

• gitlab crate

Swift

• RxGitLabKit

요청 제한

관리자 문서에서 요청 제한 설정에 대한 자세한 내용은 요청 제한을 참조하십시오. 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 API를 사용하여 CAPTCHA 응답 값을 얻기 위해 captcha_site_key를 사용합니다. Google reCAPTCHA v2만 지원됩니다.
• X-GitLab-Captcha-Response 및 X-GitLab-Spam-Log-Id 헤더가 설정된 상태로 요청을 다시 제출합니다.

export CAPTCHA_RESPONSE="<CAPTCHA 서비스에서 얻은 CAPTCHA 응답>"
export SPAM_LOG_ID="<초기 REST 응답에서 얻은 spam_log_id>"
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"