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

REST API

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을 명시할 필요는 없습니다.

참고: 위의 예시에서 gitlab.example.com을 gitlab.com으로 대체하여 GitLab.com (GitLab SaaS)를 조회하십시오. 인증으로 인해 액세스가 거부될 수 있습니다. 자세한 정보는 Authentication를 참조하세요.

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 요청의 성공 또는 실패를 진단하는 데 도움이 될 수 있습니다.

Authentication

대부분의 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"
}

참고: 배포 토큰은 GitLab 공개 API와 함께 사용할 수 없습니다. 자세한 내용은 배포 토큰을 참조하세요.

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"

더 자세한 내용은 GitLab OAuth 2.0 공급자로서를 참조하세요.

참고: 모든 OAuth 엑세스 토큰은 생성된 후 2시간 동안 유효합니다. 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"

작업 토큰

작업 토큰을 사용하여 특정 API 엔드포인트에 인증할 수 있습니다. 이를 위해 job_token 매개변수 또는 JOB-TOKEN 헤더에 토큰을 전달합니다. 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여야 합니다.

권한이 없는 액세스 토큰을 제공하면 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 요청 및 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 기능이 일반적으로 어떻게 작동하는지에 대한 개요를 제공합니다.

다음 표는 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은 다음과 같은 페이지네이션 방법을 지원합니다.

• 오프셋 기반 페이지네이션. 기본 방법으로 모든 엔드포인트에서 사용할 수 있습니다. 단, GitLab 16.5 이후로는 users 엔드포인트를 제외하고 사용 가능합니다.
• 키셋 기반 페이지네이션. 선택된 엔드포인트에 추가되었으며, 점진적으로 전개 중입니다.

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

오프셋 기반 페이징

• users 엔드포인트는 GitLab 16.5에서 오프셋 기반 페이징을 사용하지 않도록 deprecated되었으며 17.0에서 제거 예정입니다. 이 변경 사항은 파괴적인 변경입니다. 대신 이 엔드포인트에 대해 Keyset 기반 페이징을 사용하세요.

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

다음 예에서는 페이지 당 50 네임스페이스를 나열합니다:

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

참고: 오프셋 페이징에는 허용된 최대 오프셋 한도가 있습니다. Self-Managed 인스턴스에서 한도를 변경할 수 있습니다.

페이징 Link 헤더

각 응답과 함께 Link 헤더가 반환됩니다. 이 헤더들은 rel이 prev, next, first, 또는 last로 설정되어 있으며 관련 URL을 포함하고 있습니다. 직접 URL을 생성하는 대신 이러한 링크를 사용해야 합니다.

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

다음 cURL 예제에서는 페이지당 출력을 3개의 항목으로 제한(per_page=3)하고 이슈 ID가 8인 프로젝트의(9인 ID를 가지는) 코멘트의 두 번째 페이지(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 사용자의 경우, 일부 페이징 헤더가 반환되지 않을 수 있습니다.

Keyset 기반 페이징

Keyset 페이징은 페이지 검색을 더 효율적으로 만들어주며, 오프셋 기반 페이징과는 달리 런타임이 컬렉션 크기와 관계없이 독립적입니다.

이 방법은 다음과 같은 매개변수로 제어됩니다. 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 옵션에 따라 다르며, 추가 필터가 하나 이상 있을 수 있습니다.

경고: GitLab 14.0에서 W3C Link 명세에 맞추기 위해 Links 헤더가 제거되었습니다. Link 헤더는 GitLab 13.1에서 추가되었으며 대신 사용해야 합니다.

컬렉션의 끝에 도달했고 추가로 검색할 레코드가 없는 경우, Link 헤더가 없으며 결과 배열은 비어있을 것입니다.

당신은 직접 URL을 생성하는 대신 주어진 링크만 사용하여 다음 페이지를 검색해야 합니다. 표시된 헤더 외에는 추가적인 페이징 헤더를 노출하지 않습니다.

지원되는 리소스

Keyset 기반 페이지네이션은 선정된 리소스와 정렬 옵션에서만 지원됩니다.

페이지네이션 응답 헤더

성능상의 이유로 쿼리가 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는 해시 key/value 쌍을 포함하는 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 대 iid

일부 리소스에는 두 가지 유사하게 명명된 필드가 있습니다. 예를 들어, 이슈, 병합 요청, 프로젝트 마일스톤 등이 있습니다. 해당 필드는 다음과 같습니다:

• 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 대 false

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

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

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

API를 사용 중일 때 유효성 오류를 만날 수 있으며, 이 경우 API는 HTTP 400 오류를 반환합니다.

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

• API 요청의 필수 속성이 누락된 경우 (예: 이슈의 제목이 지정되지 않은 경우).
• 속성이 유효성 검사를 통과하지 않은 경우 (예: 사용자 bio가 너무 긴 경우).

속성이 누락된 경우 다음과 같은 내용을 받게 됩니다:

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 날짜에서 특정 시간을 포함하려는 경우 다음과 같이 ISO 8601 형식으로 지정할 수 있습니다.

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

쿼리 매개변수의 올바른 인코딩은 다음과 같을 것입니다.

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

타사 클라이언트

타사 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"