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`와 `iid` 비교#

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

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로 조회하지는 않습니다. 어떤 필드를 사용할지는 해당 리소스의 문서를 참고합니다.

인코딩#

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 날짜의 `+` 인코딩#

쿼리 파라미터에 +를 포함해야 한다면 대신 %2B를 사용해야 할 수 있습니다. W3 권고에 따라 +가 공백으로 해석되기 때문입니다. 예를 들어 ISO 8601 날짜에는 다음과 같이 특정 시각을 ISO 8601 형식으로 포함할 수 있습니다.

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

이 쿼리 파라미터의 올바른 인코딩은 다음과 같습니다.

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

응답 해석#

경우에 따라 API 응답이 예상과 다를 수 있습니다. null 값이나 리디렉션이 그런 사례입니다. 응답에서 숫자 상태 코드를 받으면 상태 코드를 참고합니다.

`null`과 `false` 비교#

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

불리언 인수에는 true 또는 false 값만 설정합니다(null은 설정하지 않습니다).

리디렉션#

경로 변경 이후에는 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

API는 GET 요청만 리디렉션합니다. 이동된 프로젝트의 이전 경로를 사용하는 POST, PUT, PATCH, DELETE 요청을 보내면 대부분의 엔드포인트가 405 Method Not Allowed를 반환합니다.

{
  "message": "Non GET methods are not allowed for moved projects"
}

이러한 요청에는 프로젝트 ID 또는 프로젝트의 현재 경로를 사용합니다.

페이지네이션#

GitLab은 다음 페이지네이션 방식을 지원합니다.

오프셋 기반 페이지네이션. 기본 방식이며 users 엔드포인트를 제외한 모든 엔드포인트에서 사용할 수 있습니다.
키셋 기반 페이지네이션. 일부 엔드포인트에 추가됐으며 점진적으로 확대 적용되고 있습니다.

대규모 컬렉션에서는 성능상의 이유로 오프셋 페이지네이션 대신 키셋 페이지네이션을 사용합니다(사용할 수 있는 경우).

오프셋 기반 페이지네이션#

히스토리

users 엔드포인트의 오프셋 기반 페이지네이션은 GitLab 16.5에서 지원이 중단됐고 17.0에서 제거될 예정입니다. 이 변경은 브레이킹 체인지입니다. 이 엔드포인트에는 키셋 기반 페이지네이션을 사용합니다.
GitLab 17.0의 users 엔드포인트는 요청한 레코드 수가 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`	yes	`keyset`(키셋 페이지네이션을 사용하는 경우).
`per_page`	no	페이지당 나열할 항목 수(기본값: `20`, 최대: `100`).
`order_by`	yes	정렬 기준이 되는 칼럼.
`sort`	yes	정렬 순서(`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`.	인증된 사용자와 인증되지 않은 사용자.
레지스트리 리포지터리 태그	`order_by=name`, `sort=asc`, `sort=desc`만 지원.	인증된 사용자만.
리포지터리 트리 나열	해당 없음	인증된 사용자와 인증되지 않은 사용자. 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에 도입.
러너 job	`order_by=id`, `sort=desc`만 지원	인증된 사용자만.

페이지네이션 응답 헤더#

성능상의 이유로 쿼리가 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

GitLab v19.5

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

원문 보기

번역일: 2026-10-15

요약

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`와 `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로 조회하지는 않습니다. 어떤 필드를 사용할지는 해당 리소스의 문서를 참고합니다.

인코딩#

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`과 `false` 비교#

불리언 인수에는 true 또는 false 값만 설정합니다(null은 설정하지 않습니다).

리디렉션#

경로 변경 이후에는 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

{
  "message": "Non GET methods are not allowed for moved projects"
}

이러한 요청에는 프로젝트 ID 또는 프로젝트의 현재 경로를 사용합니다.

페이지네이션#

GitLab은 다음 페이지네이션 방식을 지원합니다.

오프셋 기반 페이지네이션. 기본 방식이며 users 엔드포인트를 제외한 모든 엔드포인트에서 사용할 수 있습니다.
키셋 기반 페이지네이션. 일부 엔드포인트에 추가됐으며 점진적으로 확대 적용되고 있습니다.

대규모 컬렉션에서는 성능상의 이유로 오프셋 페이지네이션 대신 키셋 페이지네이션을 사용합니다(사용할 수 있는 경우).

오프셋 기반 페이지네이션#

히스토리

users 엔드포인트의 오프셋 기반 페이지네이션은 GitLab 16.5에서 지원이 중단됐고 17.0에서 제거될 예정입니다. 이 변경은 브레이킹 체인지입니다. 이 엔드포인트에는 키셋 기반 페이지네이션을 사용합니다.
GitLab 17.0의 users 엔드포인트는 요청한 레코드 수가 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`	yes	`keyset`(키셋 페이지네이션을 사용하는 경우).
`per_page`	no	페이지당 나열할 항목 수(기본값: `20`, 최대: `100`).
`order_by`	yes	정렬 기준이 되는 칼럼.
`sort`	yes	정렬 순서(`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`.	인증된 사용자와 인증되지 않은 사용자.
레지스트리 리포지터리 태그	`order_by=name`, `sort=asc`, `sort=desc`만 지원.	인증된 사용자만.
리포지터리 트리 나열	해당 없음	인증된 사용자와 인증되지 않은 사용자. 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에 도입.
러너 job	`order_by=id`, `sort=desc`만 지원	인증된 사용자만.

페이지네이션 응답 헤더#

성능상의 이유로 쿼리가 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

REST API 요청 보내기#

속도 제한#

응답 형식#

요청 요건#

요청 페이로드#

경로 파라미터#

id와 iid 비교#

인코딩#

네임스페이스 경로#

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

배열 및 해시 타입#

array#

hash#

해시 배열#

ISO 8601 날짜의 + 인코딩#

응답 해석#

null과 false 비교#

리디렉션#

페이지네이션#

오프셋 기반 페이지네이션#

페이지네이션 Link 헤더#

기타 페이지네이션 헤더#

키셋 기반 페이지네이션#

지원 리소스#

페이지네이션 응답 헤더#

버전 관리 및 지원 중단#

REST API

REST API 요청 보내기#

속도 제한#

응답 형식#

요청 요건#

요청 페이로드#

경로 파라미터#

id와 iid 비교#

인코딩#

네임스페이스 경로#

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

배열 및 해시 타입#

array#

hash#

해시 배열#

ISO 8601 날짜의 + 인코딩#

응답 해석#

null과 false 비교#

리디렉션#

페이지네이션#

오프셋 기반 페이지네이션#

페이지네이션 Link 헤더#

기타 페이지네이션 헤더#

키셋 기반 페이지네이션#

지원 리소스#

페이지네이션 응답 헤더#

버전 관리 및 지원 중단#

`id`와 `iid` 비교#

`array`#

`hash`#

ISO 8601 날짜의 `+` 인코딩#

`null`과 `false` 비교#

페이지네이션 `Link` 헤더#

`id`와 `iid` 비교#

`array`#

`hash`#

ISO 8601 날짜의 `+` 인코딩#

`null`과 `false` 비교#

페이지네이션 `Link` 헤더#