REST API 리소스 문서화

REST API 리소스는 Markdown으로 /doc/api 하위에 문서화되어 있습니다. 각 리소스는 자체 Markdown 파일을 가지고 있으며, 이는 api_resources.md에서 링크되어 있습니다.

Markdown을 수정하는 경우, 해당 리소스에 대한 OpenAPI 정의도 함께 업데이트해야 합니다. 해당 리소스를 위한 OpenAPI 정의가 있다면 해당되며 없는 경우 고려해야 합니다. 최신 OpenAPI 3.0.x 명세와 일치해야 합니다. (자세한 정보는 이 이슈의 토론을 참조하세요.)

리소스에 대한 Markdown 문서에서 (AKA 엔드포인트):

각 메서드는 REST API 요청을 가져야 합니다. 예를 들면:
```
GET /api/v4/projects/:id/repository/branches
```
각 메서드에는 속성에 대한 상세한 설명이 있어야 합니다.
각 메서드에는 cURL 예제가 있어야 합니다.
각 메서드에 대한 응답 본문에 대한 상세한 설명이 있어야 합니다.
각 메서드에는 응답 본문 예제가 있어야 합니다 (JSON 형식).
특정 높은 수준의 구독 티어에서만 사용 가능한 속성이 있는 경우, 해당 티어를 설명에 추가해야 합니다. Premium용 속성인 경우, Ultimate용도 가능하다는 것을 포함해야 합니다.
특정 오퍼링에서만 사용 가능한 속성이 있는 경우, 해당 오퍼링을 설명에 추가해야 합니다. 속성 설명에 오퍼링과 티어가 모두 있는 경우, 이를 결합해야 합니다. 예를 들면: Self-managed, Premium 및 Ultimate 전용.

새로운 API 문서 페이지를 추가한 후에는 전역 내비게이션에 항목을 추가해야 합니다. 예시.

API 주제 템플릿

다음 템플릿을 사용하여 시작하는 데 도움을 받으세요. 테이블에서 필요한 속성을 먼저 나열해야 합니다.

## API 이름

> - 히스토리 노트.

엔드포인트의 기능을 간단히 설명하는 한 문장 혹은 두 문장.

### 메서드 제목

> - 히스토리 노트.

메서드에 대한 설명.

```plaintext
METHOD /api/v4/endpoint
```

지원되는 속성:

| 속성                       | 유형     | 필수     | 설명                  |
|--------------------------|----------|----------|-----------------------|
| `attribute`              | 데이터유형 | 예       | 상세 설명             |
| `attribute`              | 데이터유형 | 아니요   | 상세 설명             |
| `attribute`              | 데이터유형 | 아니요   | 상세 설명             |
| `attribute`              | 데이터유형 | 아니요   | 상세 설명             |

성공할 경우, [`<status_code>`](rest/index.md#status-codes) 및 다음과 같은 응답 속성 반환:

| 속성                       | 유형     | 설명                   |
|--------------------------|----------|-------------------------|
| `attribute`              | 데이터유형 | 상세 설명             |
| `attribute`              | 데이터유형 | 상세 설명             |

예시 요청:

```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` | 문자열 | 아니요   | GitLab 14.7에서 [폐기](<link-to-issue>)되었으며 15.4에서 제거 예정입니다. 대신 `widget_id`를 사용하세요. 위젯 이름. |

폭넓게 폐기를 알리거나 파괴적인 변경인 경우, REST API 폐기 및 제거 페이지를 업데이트하세요.

메소드 설명

다음 표 머리글을 사용하여 메소드를 설명합니다. 속성은 항상 역따옴표(`)를 사용하여 코드 블록으로 지정해야 합니다.

테이블을 필수로 필요한 속성을 먼저 정렬한 다음 알파벳순으로 정렬합니다.

| Attribute                    | Type          | Required | Description                                         |
|------------------------------|---------------|----------|-----------------------------------------------------|
| `title`                      | string        | Yes      | 이슈의 제목.                                    |
| `assignee_ids`               | integer array | No       | 이슈를 지정하는 사용자의 ID입니다. 얼티메이트만 해당됩니다. |
| `confidential`               | boolean       | No       | 이슈를 비공개로 설정합니다. 기본값은 `false`입니다. |

렌더된 예시:

Attribute	Type	Required	Description
`title`	string	Yes	이슈의 제목.
`assignee_ids`	integer array	No	이슈를 지정하는 사용자의 ID입니다. 프리미엄 및 얼티메이트만 해당됩니다.
`confidential`	boolean	No	이슈를 비공개로 설정합니다. 기본값은 `false`입니다.

속성에 대한 설명 작성 방법에 대한 정보는 GraphQL API 설명 스타일 가이드를 참조하십시오.

응답 바디 설명

다음 문구로 시작하여 응답 바디를 설명하며, status code를 관련 HTTP 상태 코드로 대체합니다. 예를 들어:

요청이 성공하면 [`200 OK`](../../api/rest/index.md#status-codes) 및 다음과 같은 응답 속성을 반환합니다.

다음 표 머리글을 사용하여 응답 바디를 설명합니다. 속성은 항상 역따옴표(`)를 사용하여 코드 블록으로 지정해야 합니다.

만약 속성이 다른 객체와 같은 복합 타입인 경우, .으로 하위 속성을 나타냅니다. 즉, project.name이나 배열의 경우 projects[].name과 같이 표시합니다.

테이블을 알파벳순으로 정렬합니다.

| Attribute                    | Type          | Description                               |
|------------------------------|---------------|-------------------------------------------|
| `assignee_ids`               | integer array | 이슈를 지정하는 사용자의 ID입니다. 프리미엄 및 얼티메이트만 해당됩니다. |
| `confidential`               | boolean       | 이슈가 비공개인지 여부입니다. |
| `title`                      | string        | 이슈의 제목입니다. |

렌더된 예시:

Attribute	Type	Description
`assignee_ids`	integer array	이슈를 지정하는 사용자의 ID입니다. 프리미엄 및 얼티메이트만 해당됩니다.
`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`를 사용하여 데이터 게시

--request POST를 사용하고 매개변수를 URI에 추가하는 대신 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`를 사용하여 데이터 게시