REST API 리소스 문서화
REST API 리소스는 Markdown으로 /doc/api
아래 문서화됩니다. 각 리소스는 해당 Markdown 파일을 갖고 있으며, api_resources.md
에서 링크되어 있습니다.
Markdown을 수정할 때, 해당 리소스를 위한 OpenAPI definition을 업데이트하세요. 리소스에 대한 OpenAPI definition이 있는 경우, 해당 내용을 맞추세요. 최신 OpenAPI 3.0.x specification과 일치시키세요. (더 많은 정보는 이 issue의 토론을 참조하세요.)
리소스에 대한 Markdown 문서에서 (endpoint로도 알려짐):
-
각 메서드는 REST API 요청이 있어야 합니다. 예를 들어:
GET /api/v4/projects/:id/repository/branches
- 각 메서드에는 속성에 대한 상세한 설명이 있어야 합니다.
- 각 메서드에는 cURL 예시가 있어야 합니다.
- 각 메서드에는 응답 본문에 대한 상세한 설명이 있어야 합니다.
- 각 메서드에는 응답 본문 예시 (JSON 형식)가 있어야 합니다.
- 특정 레벨의 구독 티어에서만 사용 가능한 속성이 있는 경우, 해당 Description에 적절한 티어를 추가하세요. 특정 속성이 Premium에 유용한 경우, 해당 티어가 Ultimate에도 사용 가능하다고 포함하세요.
- 특정 제공에만 사용 가능한 속성이 있는 경우, 해당 Description에 해당 제공을 추가하세요. 속성 설명에 제공 및 티어가 모두 포함된 경우, 그것을 결합하세요. 예: Self-Managed, Premium 및 Ultimate에서만 사용 가능.
새로운 API 문서 페이지를 추가한 후, 글로벌 내비게이션에 항목을 추가하세요. 예시.
API 주제 템플릿
시작하는 데 도움이 되도록 다음 템플릿을 사용하세요. 테이블에서 필요한 모든 속성을 먼저 나열하세요.
## API 이름
> - 히스토리 노트.
엔드포인트가 하는 일에 대한 한두 문장 설명.
### 메서드 제목
> - 히스토리 노트.
메서드 설명.
```plaintext
METHOD /api/v4/endpoint
```
지원되는 속성:
| 속성 | 타입 | 필수 | 설명 |
|--------------------------|----------|----------|-----------------------|
| `속성` | 데이터타입 | Yes | 상세 설명. |
| `속성` | 데이터타입 | No | 상세 설명. |
| `속성` | 데이터타입 | No | 상세 설명. |
| `속성` | 데이터타입 | No | 상세 설명. |
성공적으로 반환되면 [`<status_code>`](rest/index.md#status-codes) 및 다음과 같은 응답 속성이 반환됩니다:
| 속성 | 타입 | 설명 |
|--------------------------|----------|-----------------------|
| `속성` | 데이터타입 | 상세 설명. |
| `속성` | 데이터타입 | 상세 설명. |
요청 예시:
```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/endpoint?parameters"
```
응답 예시:
```json
[
{
}
]
```
히스토리
새로운 API 호출 또는 업데이트에 대한 히스토리를 추가하세요.
개별 속성에 대한 히스토리를 추가하려면 해당 섹션에 포함하세요. 예를 들어:
### 위젯 편집
> - `widget_message`은 GitLab 14.3에서 [도입되었습니다](<link-to-issue>).
API 또는 속성이 피처 플래그 뒤에 배포된 경우, 해당 히스토리에 피처 플래그 정보를 포함하세요.
지원 중단
API 엔드포인트의 지원 중단을 문서화하려면 페이지나 주제의 지원 중단 방법을 따르세요.
속성을 지원 중단하려면:
-
히스토리 노트 추가.
> - `widget_name`은 GitLab 14.7에서 [지원 중단](<link-to-issue>)되었습니다.
-
설명에 인라인 지원 중단 텍스트 추가.
| 속성 | 타입 | 필수 | 설명 | |---------------|--------|----------|-------------| | `widget_name` | string | No | GitLab 14.7에서 [지원 중단](<link-to-issue>)되었으며 15.4에서 제거 예정입니다. 대신 `widget_id`를 사용하세요. 위젯의 이름. |
널리 공지하려면 또는 중대한 변경인 경우, REST API 지원 중단 및 삭제 페이지를 업데이트하세요.
메서드 설명
메서드를 설명하는 데 사용할 테이블 헤더는 다음과 같습니다. 속성은 항상 backticks (`
)를 사용하여 코드 블록으로 표시되어야 합니다.
테이블을 필수 속성이 먼저 나오도록 정렬한 후 알파벳 순으로 정렬하세요.
| 속성 | 타입 | 필수 | 설명 |
|------------------------------|---------------|----------|-----------------------------------------------------|
| `title` | string | Yes | 이슈의 제목. |
| `assignee_ids` | integer array | No | 이슈를 할당할 사용자의 ID. Ultimate에서만 사용 가능. |
| `confidential` | boolean | No | 이슈를 비밀로 설정합니다. 기본값은 `false`입니다. |
렌더링된 예시:
속성 | 타입 | 필수 | 설명 |
---|---|---|---|
title
| string | Yes | 이슈의 제목. |
assignee_ids
| integer array | No | 이슈를 할당할 사용자들의 ID. Premium 및 Ultimate에서 사용 가능. |
confidential
| boolean | No | 이슈를 비밀로 설정합니다. 기본값은 false 입니다.
|
속성 설명에 대한 자세한 정보는 GraphQL API 설명 스타일 가이드를 참조하세요.
응답 본문 설명
다음 문장으로 설명을 시작합니다. status code
대신 관련 HTTP status code로 대체합니다. 예:
성공적으로 반환되면 [`200 OK`](../../api/rest/index.md#status-codes) 및 아래와 같은 응답 속성이 반환됩니다:
다음 테이블 헤더를 사용하여 응답 본문을 설명하세요. 속성은 항상 backticks (`
)를 사용하여 코드 블록으로 표시되어야 합니다.
만약 속성이 다른 객체와 같은 복잡한 타입인 경우, 점(.
)을 사용하여 하위 속성을 나타냅니다. 예: project.name
또는 배열인 경우 projects[].name
.
테이블을 알파벳 순으로 정렬하세요.
| 속성 | 타입 | 설명 |
|------------------------------|---------------|---------------------------------------|
| `assignee_ids` | integer array | 이슈를 할당할 사용자들의 ID. Premium 및 Ultimate에서 사용 가능. |
| `confidential` | boolean | 이슈를 비밀로 설정합니다. |
| `title` | string | 이슈의 제목. |
렌더링된 예시:
속성 | 타입 | 설명 |
---|---|---|
assignee_ids
| integer array | 이슈를 할당할 사용자들의 ID. Premium 및 Ultimate에서 사용 가능. |
confidential
| boolean | 이슈를 비밀로 설정합니다. |
title
| string | 이슈의 제목. |
속성 설명에 대한 자세한 정보는 GraphQL API 설명 스타일 가이드를 참조하세요.
cURL 명령어
- 엔드포인트로
https://gitlab.example.com/api/v4/
를 사용하세요. - 필요한 경우 항상 이 개인 액세스 토큰을 사용하세요:
<your_access_token>
. - 요청을 먼저 작성하세요.
GET
이 기본값이므로 포함할 필요가 없습니다. - 가독성을 위해 긴 옵션 이름 (
-H
대신--header
)을 사용하세요. (테스트된scripts/lint-doc.sh
에도 사용됨.) - URL은
--url
매개변수로 선언하며, URL을 쌍따옴표("
)로 감싸세요. - 개인 액세스 토큰을 사용하는 예제를 선호하고, 사용자 이름 및 암호 데이터를 전달하지 마세요.
- 가독성을 위해
\
문자와 들여쓰기를 사용하여 긴 단일 행 명령을 여러 줄로 나누세요.
메서드 | 설명 |
---|---|
--header "PRIVATE-TOKEN: <your_access_token>"
| 인증이 필요한 경우 항상 이 방법을 사용하세요. |
--request POST
| 새 객체를 생성할 때 이 방법을 사용하세요. |
--request PUT
| 기존 객체를 업데이트할 때 이 방법을 사용하세요. |
--request DELETE
| 기존 객체를 제거할 때 이 방법을 사용하세요. |
cURL 예제
다음 섹션에는 cURL 예제가 포함되어 있습니다. API 문서에서 사용할 수 있습니다.
간단한 cURL 명령어
그룹의 세부 정보를 가져옵니다:
curl --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/groups/gitlab-org"
URL에 전달된 매개변수와 함께 cURL 예제
인증된 사용자의 네임스페이스에 새 프로젝트를 만듭니다:
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/projects?name=foo"
cURL의 --data
를 사용하여 데이터를 전송
URI에 매개변수를 추가하고 --request POST
를 사용하는 대신, cURL의 --data
옵션을 사용할 수 있습니다. 아래 예제는 인증된 사용자의 네임스페이스에 foo
라는 새 프로젝트를 만듭니다.
curl --data "name=foo" \
--header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/projects"
JSON 콘텐츠를 사용하여 데이터 전송
이 예제는 새 그룹을 만듭니다. 작은따옴표('
)와 큰따옴표("
) 사용에 유의하십시오.
curl --request POST \
--header "PRIVATE-TOKEN: <your_access_token>" \
--header "Content-Type: application/json" \
--data '{"path": "my-group", "name": "My group"}' \
--url "https://gitlab.example.com/api/v4/groups"
가독성을 위해 다음 형식을 사용하여 --data
를 설정할 수도 있습니다:
curl --request POST \
--url "https://gitlab.example.com/api/v4/groups" \
--header "content-type: application/json" \
--header "PRIVATE-TOKEN: <your_access_token>" \
--data '{
"path": "my-group",
"name": "My group"
}'
form-data를 사용하여 데이터 전송
JSON 또는 URL 인코딩 데이터 대신, 데이터 인코딩을 적절하게 처리하는 multipart/form-data
를 사용할 수 있습니다:
curl --request POST \
--header "PRIVATE-TOKEN: <your_access_token>" \
--form "title=ssh-key" \
--form "key=ssh-rsa AAAAB3NzaC1yc2EA..." \
--url "https://gitlab.example.com/api/v4/users/25/keys"
위의 예는 관리자에 의해 실행되며, ID가 25인 사용자 계정에 ssh-key
라는 제목의 SSH 공개 키가 추가됩니다.
특수 문자 이스케이프
때때로 공백이나 슬래시(/
)는 오류로 이어질 수 있으므로 가능한 경우 이스케이프하는 것이 좋습니다. 아래 예제에서는 제목에 공백이 포함된 새 이슈를 만듭니다. 공백이 %20
ASCII 코드를 사용하여 이스케이프되는 방법에 주목하십시오.
curl --request POST \
--header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/projects/42/issues?title=Hello%20GitLab"
슬래시(/
)의 경우 %2F
를 사용하십시오.
API 호출에 배열 전달
GitLab API는 때때로 문자열이나 정수의 배열을 허용합니다. 예를 들어 프로젝트의 사용자 디렉터리을 요청할 때 특정 사용자를 제외하려면 다음과 같이 해야 합니다.
curl --request PUT \
--header "PRIVATE-TOKEN: <your_access_token>"
--data "skip_users[]=<user_id>" \
--data "skip_users[]=<user_id>" \
--url "https://gitlab.example.com/api/v4/projects/<project_id>/users"