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 문서에서 사용할 수 있습니다.

실제 사용자, URL 또는 토큰에 대한 정보를 사용하지 마십시오. 문서의 경우 가짜 사용자 정보, 가짜 URL, 가짜 토큰의 관련 스타일 가이드 섹션을 참조하십시오.

간단한 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"

REST API 리소스 문서화

API 주제 템플릿

히스토리

지원 중단

메서드 설명

응답 본문 설명

cURL 명령어

cURL 예제

간단한 cURL 명령어

URL에 전달된 매개변수와 함께 cURL 예제

cURL의 `--data`를 사용하여 데이터를 전송

JSON 콘텐츠를 사용하여 데이터 전송

form-data를 사용하여 데이터 전송

특수 문자 이스케이프

API 호출에 배열 전달

도움말

기능 사용 가능성과 제품 평가판

도움받기

REST API 리소스 문서화

API 주제 템플릿

히스토리

지원 중단

메서드 설명

응답 본문 설명

cURL 명령어

cURL 예제

간단한 cURL 명령어

URL에 전달된 매개변수와 함께 cURL 예제

cURL의 --data를 사용하여 데이터를 전송

JSON 콘텐츠를 사용하여 데이터 전송

form-data를 사용하여 데이터 전송

특수 문자 이스케이프

API 호출에 배열 전달

도움말

기능 사용 가능성과 제품 평가판

도움받기

cURL의 `--data`를 사용하여 데이터를 전송