REST API 리소스 문서화

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

Markdown을 수정할 때는 해당 리소스에 대한 OpenAPI 정의도 업데이트하세요. 해당 리소스에 대한 OpenAPI 정의가 있는 경우 해당 사항을 일치시키세요. 최신 OpenAPI 3.0.x 사양과 일치시키세요. (자세한 정보는 이 이슈에서 논의된 내용을 참조하세요.)

리소스에 대한 Markdown 문서에서 (또한 endpoint로도 알려짐):

각 메서드에는 REST API 요청이 있어야 합니다. 예를 들면:
```
GET /api/v4/projects/:id/repository/branches
```
각 메서드에는 속성의 세부 설명이 있어야 합니다. 속성 설명.
각 메서드에는 cURL 예제가 있어야 합니다.
각 메서드에는 응답 본문(body)의 세부 설명이 있어야 합니다. 응답 본문(description).
각 메서드에는 응답 본문의 예제(JSON 형식)가 있어야 합니다.
특정 고급 구독 계층에서만 사용 가능한 속성인 경우 Description에 적절한 계층을 추가하세요. 프리미엄 전용인 경우 해당 사항을 포함하여 Ultimate에서도 사용 가능하다고 명시하세요.
특정 제공에만 사용 가능한 경우 Description에 해당 제공사항을 추가하세요. 속성의 설명에 제공과 계층을 모두 포함하는 경우 해당 내용을 결합하세요. 예를 들어: Self-managed, 프리미엄 및 얼티밋 전용.

새로운 API 문서 페이지가 추가된 후 글로벌 내비게이션에 항목을 추가하세요. 예시.

API 주제 템플릿

시작하는 데 도움이 되도록 다음 템플릿을 사용하세요. 테이블에서 필요한 모든 속성을 먼저 나열하세요.

## API 이름

> - 히스토리 노트.

종점이 하는 일에 대한 한 두 문장 설명.

### 메서드 제목

> - 히스토리 노트.

메서드에 대한 설명.

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

지원되는 속성:

| 속성           | 유형     | 필수여부 | 설명                 |
|----------------|----------|----------|---------------------|
| `attribute`              | 자료 유형 | 예      | 자세한 설명. |
| `attribute`              | 자료 유형 | 아니오       | 자세한 설명. |
| `attribute`              | 자료 유형 | 아니오       | 자세한 설명. |
| `attribute`              | 자료 유형 | 아니오       | 자세한 설명. |

성공하면 [`<status_code>`](rest/troubleshooting.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` [도입됨](https://link-to-issue) in GitLab 14.3.

API 또는 속성이 기능 플래그 뒤에 배포된 경우, 해당 기능에 대한 정보를 history에 포함시키세요.

사용 중단 사항

API 종단점의 사용 중단을 문서화하려면 페이지 또는 주제 사용 중단 단계를 따르세요.

속성을 사용 중단하려면:

히스토리 노트를 추가하세요.

> - `widget_name` [사용 중단됨](https://link-to-issue) in GitLab 14.7.

설명에 인라인 사용 중단 텍스트를 추가하세요.

| 속성     | 유형   | 필요여부 | 설명 |
|---------------|--------|----------|-------------|
| `widget_name` | string | 아니오       | GitLab 14.7에서 [사용 중단됨](https://link-to-issue) 예정이며 15.4에 제거될 예정입니다. `widget_id` 대신 사용하세요. 위젯의 이름. |

사용 중단을 널리 알리려면 또는 이것이 파손 변경이면 REST API 사용 중단 및 삭제 페이지를 업데이트하세요.

메서드 설명

다음 테이블 헤더를 사용하여 메서드를 설명하세요. 속성은 코드 블록을 사용하여 항상 역따옴표 (`)로 묶여야 합니다.

필수 속성부터 알파벳순으로 테이블을 정렬하세요.

| 속성                    | 유형          | 필수여부 | 설명                                         |
|------------------------------|---------------|----------|-----------------------------------------------------|
| `title`                      | string        | 예      | 이슈의 제목.                                 |
| `assignee_ids`               | integer array | 아니오       | 이슈를 할당할 사용자의 ID. 얼티밋 전용. |
| `confidential`               | boolean       | 아니오       | 이슈를 비밀로 설정합니다. 기본값은 `false`입니다. |

렌더된 예제:

속성	유형	필수여부	설명
`title`	string	예	이슈의 제목.
`assignee_ids`	integer array	아니오	이슈를 할당할 사용자의 ID. 프리미엄 및 얼티밋 전용.
`confidential`	boolean	아니오	이슈를 비밀로 설정합니다. 기본값은 `false`입니다.

속성 설명 작성에 대한 자세한 정보는 GraphQL API 설명 스타일 가이드를 참조하세요.

조건부 필수 속성

API 요청을 만드는 데 필요한 속성이 혼자서 또는 함께 필요한 속성이 있는 경우:

필수여부 열에 조건부를 추가하세요.

설명에서 관련 속성을 명확하게 설명하세요. 다음 템플릿을 사용할 수 있습니다:

`attribute1` 또는 `attribute2` 중 하나 이상은 API 호출에 포함되어야 합니다. 필요한 경우 둘 다 사용할 수 있습니다.

예를 들어:

속성	유형	필수여부	설명
`include_saml_users`	boolean	조건부	SAML 식별자로 사용자를 포함합니다. `include_saml_users` 또는 `include_service_accounts` 중 하나 이상을 `true`로 설정해야 합니다. 필요한 경우 둘 다 사용할 수 있습니다.
`include_service_accounts`	boolean	조건부	서비스 계정 사용자를 포함합니다. `include_saml_users` 또는 `include_service_accounts` 중 하나 이상을 `true`로 설정해야 합니다. 필요한 경우 둘 다 사용할 수 있습니다.

응답 본문 설명

다음 문장으로 설명을 시작하십시오. status code를 관련 HTTP 상태 코드로 바꿔주세요. 예를 들면:

성공하면, [`200 OK`](../../api/rest/troubleshooting.md#status-codes) 및
다음 응답 속성을 반환합니다:

다음 표 머릿글을 사용하여 응답 본문을 설명합니다. 속성은 항상 역따옴표 (`)를 사용하여 코드 블록으로 표시되어야 합니다.

속성이 다른 객체와 같은 복합 유형인 경우 .(점)으로 하위 속성을 나타내십시오. 예를 들어 배열인 경우 project.name 또는 projects[].name입니다.

테이블을 알파벳순으로 정렬하십시오.

| 속성                      | 유형             | 설명                         |
|---------------------------|-----------------|-------------------------------|
| `assignee_ids`            | 정수 배열          | 문제를 할당할 사용자의 ID입니다. 프리미엄 및 얼티밋 전용입니다.           |
| `confidential`            | 부울              | 문제가 기밀인지 아닌지 여부입니다.        |
| `title`                   | 문자열            | 문제의 제목입니다.                 |

렌더링된 예시:

Attribute	Type	Description
`assignee_ids`	integer array	IDs of the users to assign the issue to. Premium and Ultimate only.
`confidential`	boolean	Whether the issue is confidential or not.
`title`	string	Title of the issue.

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

cURL 명령

끝점으로 https://gitlab.example.com/api/v4/을 사용하십시오.
필요할 때마다 이 개인 액세스 토큰을 사용하십시오: <your_access_token>.
요청을 항상 먼저 넣으십시오. GET은 기본값이므로 포함시키지 않아도 됩니다.
가독성을 위해 긴 옵션 이름(--header 대신 -H)을 사용하십시오. (scripts/lint-doc.sh에서 테스트됨.)
URL을 --url 매개변수로 선언하고, URL을 큰 따옴표(")로 감싸십시오.
가독성을 위해 긴 단일 라인 명령을 여러 줄로 나누기 위해 \ 문자와 들여쓰기를 사용하십시오.

메서드	설명
`--header "PRIVATE-TOKEN: <your_access_token>"`	인증이 필요할 때 항상이 방법을 사용하십시오.
`--request POST`	새 객체를 만들 때 이 방법을 사용하십시오.
`--request PUT`	기존 객체를 업데이트할 때 이 방법을 사용하십시오.
`--request DELETE`	기존 객체를 제거할 때 이 방법을 사용하십시오.

cURL 예제

다음 섹션에는 API 문서에서 사용할 수 있는 일련의 cURL 예제가 포함되어 있습니다.

경고: 실제 사용자, 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를 사용하고 매개변수를 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`를 사용한 데이터 게시