• 호환성 가이드라인
  • 현재 상태
• API 사용 방법
  • 유효한 API 요청
  • HTTP 응답 헤더 노출을 위한 API 요청
  • 종료 코드를 포함하는 API 요청
• 인증
  • OAuth 2.0 토큰
  • 개인/프로젝트/그룹 액세스 토큰
  • 작업 토큰
  • 세션 쿠키
  • 가장하기 토큰
    • 사용자 변경 권한 비활성화
  • Sudo
• 상태 코드
• 리다이렉트
• 페이지네이션
  • 오프셋 기반 페이징
    • 페이지네이션 Link 헤더
    • 기타 페이지네이션 헤더
  • 키패드 기반 페이징
    • 지원되는 리소스
  • 페이징 응답 헤더
• 경로 매개변수
• 네임스페이스 경로 인코딩
• 파일 경로, 브랜치 및 태그 이름 인코딩
• 요청 페이로드
• array 및 hash 유형의 API 매개변수 인코딩
  • array
  • hash
  • 해시의 배열
• id vs iid
• null vs 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 릴리스와 함께 이뤄집니다.

모든 deprecation 및 버전 간 변경 내용은 문서에 기재되어 있습니다.

현재 상태

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 토큰을 사용하여 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 제공자로 사용에 대해 자세히 알아보세요.

개인/프로젝트/그룹 액세스 토큰

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

작업 토큰

job tokens를 사용하여 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을 재구성(리눅스 패키지 설치)하거나 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 요청 및 사용자 이름을 제공하여 cURL을 사용한 sudo 요청의 예시:

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 요청 및 ID를 제공하여 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 기능의 일반적인 동작을 보여줍니다.

다음 표는 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
...
This resource has been moved permanently to https://gitlab.example.com/api/v4/projects/81

페이지네이션

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

• 오프셋 기반 페이지네이션. 기본 방식으로 GitLab 16.5 이후를 제외한 모든 엔드포인트에서 사용 가능합니다.
• 키셋 기반 페이지네이션. 선택된 엔드포인트에 추가되었으며 점진적으로 배포 중입니다.

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

오프셋 기반 페이징

• users 엔드포인트는 GitLab 16.5에서 오프셋 기반 페이징으로 사용 중지되었으며, 17.0에서 제거 예정입니다. 이 변경 사항은 파손(change) 됩니다. 이 엔드포인트에 대해 대신 키패드(keyset)-기반 페이징을 사용하세요.
• users 엔드포인트는 GitLab 17.0에서 요청된 레코드 수가 50,000을 초과하는 경우 키패드(keyset)-기반 페이징을 적용합니다.

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

다음 예에서는 페이지당 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인 프로젝트의 (project_id=9) 코멘트의 두 번째 페이지 (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 모두 필수입니다.

다음 예에서는 페이지당 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가 포함되어 있습니다.

다른 예시로, 다음 요청은 키패드 페이지네이션을 사용하여 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 헤더가 없으며 결과 배열이 비어 있습니다.

나만 주어진 링크를 사용하여 다음 페이지를 검색해야 하며, 표시된 헤더 이외에는 추가 페이지네이션 헤더를 노출하지 않습니다.

지원되는 리소스

키패드 기반 페이징은 선택된 리소스와 정렬 옵션에 대해서만 지원됩니다:

페이징 응답 헤더

성능상의 이유로 쿼리가 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를 반환합니다. (예: Aache 같은 것 앞에 있을 경우) URL 인코딩된 경로 매개변수가 디코딩되지 않도록 주의해야 합니다.

네임스페이스 경로 인코딩

네임스페이스 API 요청을 사용하는 경우, NAMESPACE/PROJECT_PATH가 URL 인코딩되었는지 확인하세요.

예를 들어, /는 %2F로 표시됩니다:

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

프로젝트의 _path_가 반드시 _name_과 동일하지는 않습니다. 프로젝트의 _path_는 프로젝트의 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는 해시 키/값 쌍을 포함하는 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: 단일 프로젝트 범위 내에서 고유한 (웹 UI에 표시되는) 내부 ID입니다.

리소스가 iid 필드와 id 필드 둘 다 가지고 있다면, 리소스를 가져오기 위해 일반적으로 iid 필드가 id 대신 사용됩니다.

예를 들어, 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와 동일하게 취급합니다.

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

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

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": {
        "<속성-이름>": [
            "<오류-메시지>",
            "<오류-메시지>",
            ...
        ],
        "<쵸속-엔티티>": {
            "<속성-이름>": [
                "<오류-메시지>",
                "<오류-메시지>",
                ...
            ],
        }
    }
}

알 수 없는 경로

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 커뮤니티 포럼을 사용하세요.

C#

• GitLabApiClient
• NGitLab

Go

• go-gitlab

Haskell

• gitlab-haskell

Java

• gitlab4j-api
• java-gitlab-api

Node.js

• gitlab-yaac
• backbone-gitlab
• @gitbeaker/rest

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도 지원합니다.

API 엔드포인트는 명시적으로 문서화되지 않는 이상 기본적으로 text/plain을 지원하지 않습니다.

스팸으로 감지된 요청 해결

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"