REST API

요약

GitLab REST API로 워크플로를 자동화하고 통합을 구축합니다: REST API는 기존 도구 및 시스템과의 호환성을 위해 표준 HTTP 메서드와 JSON 데이터 형식을 사용합니다. REST API 요청은 루트 엔드포인트와 경로로 시작해야 합니다.

GitLab REST API로 워크플로를 자동화하고 통합을 구축합니다:

수동 개입 없이 대규모로 GitLab 리소스를 관리하는 사용자 정의 도구를 만듭니다.
GitLab 데이터를 애플리케이션에 직접 통합하여 협업을 개선합니다.
여러 프로젝트에 걸쳐 CI/CD 프로세스를 정밀하게 관리합니다.
조직 전체에서 일관된 권한을 유지하기 위해 사용자 액세스를 프로그래밍 방식으로 제어합니다.

REST API는 기존 도구 및 시스템과의 호환성을 위해 표준 HTTP 메서드와 JSON 데이터 형식을 사용합니다.

REST API 요청 만들기#

REST API 요청을 만들려면:

REST API 클라이언트를 사용하여 API 엔드포인트에 요청을 제출합니다.
GitLab 인스턴스가 요청에 응답합니다. 상태 코드와 해당되는 경우 요청한 데이터를 반환합니다. 상태 코드는 요청 결과를 나타내며 문제 해결 시 유용합니다.

REST API 요청은 루트 엔드포인트와 경로로 시작해야 합니다.

루트 엔드포인트는 GitLab 호스트 이름입니다.
경로는 /api/v4로 시작해야 합니다(v4는 API 버전을 나타냄).

다음 예시에서 API 요청은 GitLab 호스트 gitlab.example.com의 모든 프로젝트 목록을 검색합니다:

curl --request GET \
  --url "https://gitlab.example.com/api/v4/projects"

일부 엔드포인트에 대한 액세스에는 인증이 필요합니다. 자세한 내용은 인증을 참조하세요.

속도 제한#

REST API 요청은 속도 제한 설정의 적용을 받습니다. 이러한 설정은 GitLab 인스턴스가 과부하될 위험을 줄입니다.

자세한 내용은 속도 제한을 참조하세요.
GitLab.com에서 사용하는 속도 제한 설정에 대한 자세한 내용은 GitLab.com 특정 속도 제한을 참조하세요.

응답 형식#

REST API 응답은 JSON 형식으로 반환됩니다. 일부 API 엔드포인트는 일반 텍스트 형식도 지원합니다. 엔드포인트가 지원하는 콘텐츠 유형을 확인하려면 REST API 리소스를 참조하세요.

요청 요구 사항#

일부 REST API 요청에는 사용되는 데이터 형식 및 인코딩을 포함한 특정 요구 사항이 있습니다.

요청 페이로드#

API 요청은 쿼리 문자열 또는 페이로드 본문으로 전송된 매개변수를 사용할 수 있습니다. GET 요청은 일반적으로 쿼리 문자열을 전송하고, PUT 또는 POST 요청은 일반적으로 페이로드 본문을 전송합니다:

쿼리 문자열:

curl --request POST \
  --url "https://gitlab.example.com/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.example.com/api/v4/projects"

URL 인코딩된 쿼리 문자열에는 길이 제한이 있습니다. 너무 큰 요청은 414 Request-URI Too Large 오류 메시지를 반환합니다. 페이로드 본문을 사용하여 이 문제를 해결할 수 있습니다.

경로 매개변수#

엔드포인트에 경로 매개변수가 있으면 문서에 앞에 콜론이 표시됩니다.

예를 들어:

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>" \
  --url "https://gitlab.example.com/api/v4/projects/5/share/17"

URL 인코딩이 필요한 경로 매개변수를 따라야 합니다. 그렇지 않으면 API 엔드포인트와 일치하지 않아 404로 응답합니다. API 앞에 무언가가 있는 경우(예: Apache), URL 인코딩된 경로 매개변수를 디코딩하지 않는지 확인합니다.

`id` vs `iid`#

일부 API 리소스에는 이름이 비슷한 두 개의 필드가 있습니다. 예를 들어 이슈, 머지 리퀘스트 및 프로젝트 마일스톤의 경우입니다. 필드는 다음과 같습니다:

id: 모든 프로젝트에서 고유한 ID.
iid: 단일 프로젝트 범위 내에서 고유하며 웹 UI에 표시되는 추가 내부 ID.

리소스에 iid 필드와 id 필드가 모두 있는 경우, 리소스를 가져오는 데 일반적으로 id 대신 iid 필드가 사용됩니다.

예를 들어, id: 42인 프로젝트에 id: 46 및 iid: 5인 이슈가 있다고 가정합니다. 이 경우:

이슈를 검색하는 유효한 API 요청은 GET /projects/42/issues/5입니다.
이슈를 검색하는 유효하지 않은 API 요청은 GET /projects/42/issues/46입니다.

iid 필드가 있는 모든 리소스가 iid로 가져와지는 것은 아닙니다. 사용할 필드에 대한 지침은 특정 리소스 문서를 참조하세요.

인코딩#

REST API 요청을 만들 때 일부 콘텐츠는 특수 문자 및 데이터 구조를 처리하기 위해 인코딩해야 합니다.

네임스페이스 경로#

네임스페이스 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

배열 및 해시 유형#

array 및 hash 유형 매개변수로 API를 요청할 수 있습니다:

`array`#

import_sources는 array 유형의 매개변수입니다:

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  -d "import_sources[]=github" \
  -d "import_sources[]=bitbucket" \
  --url "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" \
  --url "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>" \
  --url "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"} ] }' \
  --url "https://gitlab.example.com/api/v4/projects/169/pipeline"

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 응답이 예상과 다를 수 있습니다. 문제에는 null 값과 리디렉션이 포함될 수 있습니다. 응답에서 숫자 상태 코드를 받으면 상태 코드를 참조하세요.

`null` vs `false`#

API 응답에서 일부 불리언 필드는 null 값을 가질 수 있습니다. null 불리언은 기본값이 없으며 true도 false도 아닙니다. GitLab은 불리언 필드의 null 값을 false와 동일하게 처리합니다.

불리언 인수에서는 true 또는 false 값만 설정해야 합니다(null 아님).

리디렉션#

히스토리

GitLab 16.4에서 api_redirect_moved_projects라는 플래그와 함께 도입되었습니다. 기본적으로 비활성화되어 있습니다.
GitLab 16.7에서 일반적으로 사용 가능합니다. 기능 플래그 api_redirect_moved_projects가 제거되었습니다.

경로 변경 후 REST API는 엔드포인트가 이동했다는 메시지로 응답할 수 있습니다. 이 경우 Location 헤더에 지정된 엔드포인트를 사용합니다.

다른 경로로 이동된 프로젝트의 예:

curl --request GET \
  --verbose \
  --url "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 엔드포인트를 제외한 모든 엔드포인트에서 사용 가능합니다.
키셋 기반 페이지 매김. 선택된 엔드포인트에 추가되었으며 점진적으로 롤아웃 중입니다.

성능상의 이유로 대규모 컬렉션에는 가능한 경우 오프셋 페이지 매김 대신 키셋 페이지 매김을 사용해야 합니다.

오프셋 기반 페이지 매김#

히스토리

users 엔드포인트는 GitLab 16.5에서 오프셋 기반 페이지 매김에 대해 사용 중단되었으며 17.0에서 제거될 예정입니다. 이 변경은 브레이킹 체인지입니다. 이 엔드포인트에는 키셋 기반 페이지 매김을 대신 사용합니다.
users 엔드포인트는 GitLab 17.0에서 요청된 레코드 수가 50,000개를 초과할 경우 키셋 기반 페이지 매김을 강제합니다.

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

매개변수	설명
`page`	페이지 번호 (기본값: `1`).
`per_page`	페이지당 나열할 항목 수 (기본값: `20`, 최대: `100`).

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

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

Note

오프셋 기반 페이지 매김에 대한 최대 허용 오프셋 제한이 있습니다. GitLab Self-Managed 인스턴스에서 제한을 변경할 수 있습니다.

페이지 매김 `Link` 헤더#

Link 헤더는 각 응답과 함께 반환됩니다. rel이 prev, next, first 또는 last로 설정되어 있으며 관련 URL이 포함됩니다. 자체 URL을 생성하는 대신 반드시 이러한 링크를 사용하세요.

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

다음 cURL 예는 출력을 페이지당 3개 항목으로 제한하고(per_page=3), ID 9의 프로젝트에 속한 ID 8인 이슈의 댓글의 두 번째 페이지(page=2)를 요청합니다:

curl --request GET \
  --head \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "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`	예	`keyset` (키셋 페이지 매김을 활성화하려면).
`per_page`	아니오	페이지당 나열할 항목 수 (기본값: `20`, 최대: `100`).
`order_by`	예	정렬 기준 컬럼.
`sort`	예	정렬 순서 (`asc` 또는 `desc`)

다음 예는 id 오름차순으로 정렬된 페이지당 50개의 프로젝트를 나열합니다.

curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "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>" \
  --url "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가 포함됩니다.

X-NEXT-CURSOR 헤더에는 다음 페이지의 레코드를 검색하기 위한 커서 값이 포함되어 있으며, X-PREV-CURSOR 헤더에는 사용 가능한 경우 이전 페이지의 커서 값이 포함됩니다.

필터 유형은 사용된 order_by 옵션에 따라 다르며 추가 필터가 둘 이상 있을 수 있습니다.

Warning

Links 헤더는 W3C Link 사양에 맞추기 위해 제거되었습니다. 대신 Link 헤더를 사용해야 합니다.

컬렉션의 끝에 도달하여 검색할 추가 레코드가 없으면 Link 헤더가 없고 결과 배열이 비어 있습니다.

자체 URL을 빌드하는 대신 제공된 링크만 사용하여 다음 페이지를 검색해야 합니다. 표시된 헤더 외에 추가 페이지 매김 헤더는 노출되지 않습니다.

지원되는 리소스#

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

리소스	옵션	가용성
그룹 감사 이벤트	`order_by=id`, `sort=desc`만	인증된 사용자만.
그룹	`order_by=name`, `sort=asc`만	인증되지 않은 사용자만.
인스턴스 감사 이벤트	`order_by=id`, `sort=desc`만	인증된 사용자만.
패키지 파이프라인	`order_by=id`, `sort=desc`만	인증된 사용자만.
프로젝트 Job	`order_by=id`, `sort=desc`만	인증된 사용자만.
프로젝트 감사 이벤트	`order_by=id`, `sort=desc`만	인증된 사용자만.
프로젝트	`order_by=id`만	인증된 사용자 및 인증되지 않은 사용자.
사용자	`order_by=id`, `order_by=name`, `order_by=username`, `order_by=created_at` 또는 `order_by=updated_at`.	인증된 사용자 및 인증되지 않은 사용자. GitLab 16.5에서 도입.
레지스트리 리포지터리 태그	`order_by=name`, `sort=asc` 또는 `sort=desc`만.	인증된 사용자만.
리포지터리 트리 나열	N/A	인증된 사용자 및 인증되지 않은 사용자. GitLab 17.1에서 도입.
프로젝트 이슈	`order_by=created_at`, `order_by=updated_at`, `order_by=title`, `order_by=id`, `order_by=weight`, `order_by=due_date`, `order_by=relative_position`, `sort=asc` 또는 `sort=desc`만.	인증된 사용자 및 인증되지 않은 사용자. GitLab 18.3에서 도입.

페이지 매김 응답 헤더#

성능상의 이유로 쿼리가 10,000개 이상의 레코드를 반환하면 GitLab은 다음 헤더를 반환하지 않습니다:

x-total.
x-total-pages.
rel="last" link

버전 관리 및 사용 중단#

REST API 버전은 시맨틱 버전 관리 명세를 준수합니다. 주요 버전 번호는 4입니다. 하위 호환되지 않는 변경을 위해서는 이 버전 번호를 변경해야 합니다.

마이너 버전은 명시적이지 않으며, 이는 안정적인 API 엔드포인트를 허용합니다.
새 기능은 동일한 버전 번호의 API에 추가됩니다.
주요 API 버전 변경 및 전체 API 버전 제거는 주요 GitLab 릴리스와 함께 수행됩니다.
버전 간 모든 사용 중단 및 변경 사항은 문서에 기록됩니다.

다음은 사용 중단 프로세스에서 제외되며 사전 통지 없이 언제든지 제거될 수 있습니다:

REST API 리소스에서 실험적 또는 베타로 표시된 요소.
기능 플래그 뒤에 있으며 기본적으로 비활성화된 필드.

GitLab Self-Managed의 경우 EE 인스턴스에서 CE로 되돌리면 브레이킹 체인지가 발생합니다.

REST API

Tier: Free, Premium, Ultimate
Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

원문 보기

번역일: 2026-05-22

요약

GitLab REST API로 워크플로를 자동화하고 통합을 구축합니다:

수동 개입 없이 대규모로 GitLab 리소스를 관리하는 사용자 정의 도구를 만듭니다.
GitLab 데이터를 애플리케이션에 직접 통합하여 협업을 개선합니다.
여러 프로젝트에 걸쳐 CI/CD 프로세스를 정밀하게 관리합니다.
조직 전체에서 일관된 권한을 유지하기 위해 사용자 액세스를 프로그래밍 방식으로 제어합니다.

REST API는 기존 도구 및 시스템과의 호환성을 위해 표준 HTTP 메서드와 JSON 데이터 형식을 사용합니다.

REST API 요청 만들기#

REST API 요청을 만들려면:

REST API 클라이언트를 사용하여 API 엔드포인트에 요청을 제출합니다.
GitLab 인스턴스가 요청에 응답합니다. 상태 코드와 해당되는 경우 요청한 데이터를 반환합니다. 상태 코드는 요청 결과를 나타내며 문제 해결 시 유용합니다.

REST API 요청은 루트 엔드포인트와 경로로 시작해야 합니다.

루트 엔드포인트는 GitLab 호스트 이름입니다.
경로는 /api/v4로 시작해야 합니다(v4는 API 버전을 나타냄).

다음 예시에서 API 요청은 GitLab 호스트 gitlab.example.com의 모든 프로젝트 목록을 검색합니다:

curl --request GET \
  --url "https://gitlab.example.com/api/v4/projects"

일부 엔드포인트에 대한 액세스에는 인증이 필요합니다. 자세한 내용은 인증을 참조하세요.

속도 제한#

REST API 요청은 속도 제한 설정의 적용을 받습니다. 이러한 설정은 GitLab 인스턴스가 과부하될 위험을 줄입니다.

자세한 내용은 속도 제한을 참조하세요.
GitLab.com에서 사용하는 속도 제한 설정에 대한 자세한 내용은 GitLab.com 특정 속도 제한을 참조하세요.

응답 형식#

요청 요구 사항#

일부 REST API 요청에는 사용되는 데이터 형식 및 인코딩을 포함한 특정 요구 사항이 있습니다.

요청 페이로드#

쿼리 문자열:

curl --request POST \
  --url "https://gitlab.example.com/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.example.com/api/v4/projects"

경로 매개변수#

엔드포인트에 경로 매개변수가 있으면 문서에 앞에 콜론이 표시됩니다.

예를 들어:

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>" \
  --url "https://gitlab.example.com/api/v4/projects/5/share/17"

`id` vs `iid`#

id: 모든 프로젝트에서 고유한 ID.
iid: 단일 프로젝트 범위 내에서 고유하며 웹 UI에 표시되는 추가 내부 ID.

리소스에 iid 필드와 id 필드가 모두 있는 경우, 리소스를 가져오는 데 일반적으로 id 대신 iid 필드가 사용됩니다.

예를 들어, id: 42인 프로젝트에 id: 46 및 iid: 5인 이슈가 있다고 가정합니다. 이 경우:

이슈를 검색하는 유효한 API 요청은 GET /projects/42/issues/5입니다.
이슈를 검색하는 유효하지 않은 API 요청은 GET /projects/42/issues/46입니다.

iid 필드가 있는 모든 리소스가 iid로 가져와지는 것은 아닙니다. 사용할 필드에 대한 지침은 특정 리소스 문서를 참조하세요.

인코딩#

REST API 요청을 만들 때 일부 콘텐츠는 특수 문자 및 데이터 구조를 처리하기 위해 인코딩해야 합니다.

네임스페이스 경로#

네임스페이스 API 요청을 사용하는 경우 NAMESPACE/PROJECT_PATH를 URL 인코딩해야 합니다.

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

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

파일 경로, 브랜치 및 태그 이름#

파일 경로, 브랜치 또는 태그에 /가 포함된 경우 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

배열 및 해시 유형#

array 및 hash 유형 매개변수로 API를 요청할 수 있습니다:

`array`#

import_sources는 array 유형의 매개변수입니다:

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  -d "import_sources[]=github" \
  -d "import_sources[]=bitbucket" \
  --url "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" \
  --url "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>" \
  --url "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"} ] }' \
  --url "https://gitlab.example.com/api/v4/projects/169/pipeline"

ISO 8601 날짜에서 `+` 인코딩#

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

쿼리 매개변수에 대한 올바른 인코딩은 다음과 같습니다:

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

응답 평가#

`null` vs `false`#

불리언 인수에서는 true 또는 false 값만 설정해야 합니다(null 아님).

리디렉션#

히스토리

GitLab 16.4에서 api_redirect_moved_projects라는 플래그와 함께 도입되었습니다. 기본적으로 비활성화되어 있습니다.
GitLab 16.7에서 일반적으로 사용 가능합니다. 기능 플래그 api_redirect_moved_projects가 제거되었습니다.

경로 변경 후 REST API는 엔드포인트가 이동했다는 메시지로 응답할 수 있습니다. 이 경우 Location 헤더에 지정된 엔드포인트를 사용합니다.

다른 경로로 이동된 프로젝트의 예:

curl --request GET \
  --verbose \
  --url "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 엔드포인트를 제외한 모든 엔드포인트에서 사용 가능합니다.
키셋 기반 페이지 매김. 선택된 엔드포인트에 추가되었으며 점진적으로 롤아웃 중입니다.

성능상의 이유로 대규모 컬렉션에는 가능한 경우 오프셋 페이지 매김 대신 키셋 페이지 매김을 사용해야 합니다.

오프셋 기반 페이지 매김#

히스토리

users 엔드포인트는 GitLab 16.5에서 오프셋 기반 페이지 매김에 대해 사용 중단되었으며 17.0에서 제거될 예정입니다. 이 변경은 브레이킹 체인지입니다. 이 엔드포인트에는 키셋 기반 페이지 매김을 대신 사용합니다.
users 엔드포인트는 GitLab 17.0에서 요청된 레코드 수가 50,000개를 초과할 경우 키셋 기반 페이지 매김을 강제합니다.

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

매개변수	설명
`page`	페이지 번호 (기본값: `1`).
`per_page`	페이지당 나열할 항목 수 (기본값: `20`, 최대: `100`).

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

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

Note

오프셋 기반 페이지 매김에 대한 최대 허용 오프셋 제한이 있습니다. GitLab Self-Managed 인스턴스에서 제한을 변경할 수 있습니다.

페이지 매김 `Link` 헤더#

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

curl --request GET \
  --head \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "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`	예	`keyset` (키셋 페이지 매김을 활성화하려면).
`per_page`	아니오	페이지당 나열할 항목 수 (기본값: `20`, 최대: `100`).
`order_by`	예	정렬 기준 컬럼.
`sort`	예	정렬 순서 (`asc` 또는 `desc`)

다음 예는 id 오름차순으로 정렬된 페이지당 50개의 프로젝트를 나열합니다.

curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "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>" \
  --url "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 옵션에 따라 다르며 추가 필터가 둘 이상 있을 수 있습니다.

Warning

Links 헤더는 W3C Link 사양에 맞추기 위해 제거되었습니다. 대신 Link 헤더를 사용해야 합니다.

컬렉션의 끝에 도달하여 검색할 추가 레코드가 없으면 Link 헤더가 없고 결과 배열이 비어 있습니다.

자체 URL을 빌드하는 대신 제공된 링크만 사용하여 다음 페이지를 검색해야 합니다. 표시된 헤더 외에 추가 페이지 매김 헤더는 노출되지 않습니다.

지원되는 리소스#

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

리소스	옵션	가용성
그룹 감사 이벤트	`order_by=id`, `sort=desc`만	인증된 사용자만.
그룹	`order_by=name`, `sort=asc`만	인증되지 않은 사용자만.
인스턴스 감사 이벤트	`order_by=id`, `sort=desc`만	인증된 사용자만.
패키지 파이프라인	`order_by=id`, `sort=desc`만	인증된 사용자만.
프로젝트 Job	`order_by=id`, `sort=desc`만	인증된 사용자만.
프로젝트 감사 이벤트	`order_by=id`, `sort=desc`만	인증된 사용자만.
프로젝트	`order_by=id`만	인증된 사용자 및 인증되지 않은 사용자.
사용자	`order_by=id`, `order_by=name`, `order_by=username`, `order_by=created_at` 또는 `order_by=updated_at`.	인증된 사용자 및 인증되지 않은 사용자. GitLab 16.5에서 도입.
레지스트리 리포지터리 태그	`order_by=name`, `sort=asc` 또는 `sort=desc`만.	인증된 사용자만.
리포지터리 트리 나열	N/A	인증된 사용자 및 인증되지 않은 사용자. GitLab 17.1에서 도입.
프로젝트 이슈	`order_by=created_at`, `order_by=updated_at`, `order_by=title`, `order_by=id`, `order_by=weight`, `order_by=due_date`, `order_by=relative_position`, `sort=asc` 또는 `sort=desc`만.	인증된 사용자 및 인증되지 않은 사용자. GitLab 18.3에서 도입.

페이지 매김 응답 헤더#

성능상의 이유로 쿼리가 10,000개 이상의 레코드를 반환하면 GitLab은 다음 헤더를 반환하지 않습니다:

x-total.
x-total-pages.
rel="last" link

버전 관리 및 사용 중단#

마이너 버전은 명시적이지 않으며, 이는 안정적인 API 엔드포인트를 허용합니다.
새 기능은 동일한 버전 번호의 API에 추가됩니다.
주요 API 버전 변경 및 전체 API 버전 제거는 주요 GitLab 릴리스와 함께 수행됩니다.
버전 간 모든 사용 중단 및 변경 사항은 문서에 기록됩니다.

다음은 사용 중단 프로세스에서 제외되며 사전 통지 없이 언제든지 제거될 수 있습니다:

REST API 리소스에서 실험적 또는 베타로 표시된 요소.
기능 플래그 뒤에 있으며 기본적으로 비활성화된 필드.

GitLab Self-Managed의 경우 EE 인스턴스에서 CE로 되돌리면 브레이킹 체인지가 발생합니다.

REST API

REST API 요청 만들기#

속도 제한#

응답 형식#

요청 요구 사항#

요청 페이로드#

경로 매개변수#

id vs iid#

인코딩#

네임스페이스 경로#

파일 경로, 브랜치 및 태그 이름#

배열 및 해시 유형#

array#

hash#

해시 배열#

ISO 8601 날짜에서 + 인코딩#

응답 평가#

null vs false#

리디렉션#

페이지 매김#

오프셋 기반 페이지 매김#

페이지 매김 Link 헤더#

기타 페이지 매김 헤더#

키셋 기반 페이지 매김#

지원되는 리소스#

페이지 매김 응답 헤더#

버전 관리 및 사용 중단#

REST API 요청 만들기#

속도 제한#

응답 형식#

요청 요구 사항#

요청 페이로드#

경로 매개변수#

id vs iid#

인코딩#

네임스페이스 경로#

파일 경로, 브랜치 및 태그 이름#

배열 및 해시 유형#

array#

hash#

해시 배열#

ISO 8601 날짜에서 + 인코딩#

응답 평가#

null vs false#

리디렉션#

페이지 매김#

오프셋 기반 페이지 매김#

페이지 매김 Link 헤더#

기타 페이지 매김 헤더#

키셋 기반 페이지 매김#

지원되는 리소스#

페이지 매김 응답 헤더#

버전 관리 및 사용 중단#

`id` vs `iid`#

`array`#

`hash`#

ISO 8601 날짜에서 `+` 인코딩#

`null` vs `false`#

페이지 매김 `Link` 헤더#

`id` vs `iid`#

`array`#

`hash`#

ISO 8601 날짜에서 `+` 인코딩#

`null` vs `false`#

페이지 매김 `Link` 헤더#