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

Markdown 또는 API 코드를 수정할 때는 bin/rake gitlab:openapi:v2:generate 및 bin/rake gitlab:openapi:v3:generate를 실행하여 해당 OpenAPI 정의도 업데이트하세요. OpenAPI 정의의 업데이트 필요 여부를 확인하려면 bin/rake gitlab:openapi:v2:check_docs 및 bin/rake gitlab:openapi:v3:check_docs를 실행할 수 있습니다. 이는 API 코드 또는 문서를 수정하는 커밋에 대해 실행되는 openapi-doc-check CI/CD job에서도 확인됩니다.

API 리소스에 대한 Markdown 토픽에는 다음 내용이 포함되어야 합니다:

• HTTP 메서드(GET, PUT, DELETE 등)와 요청 경로를 포함하는 블록. 항상 경로는 /로 시작합니다. 예:

  GET /api/v4/projects/:id/repository/branches
  

• 속성 요청에 대한 자세한 설명.

• 응답 본문에 대한 자세한 설명.

• cURL 예시.

• 응답 본문 예시(JSON 형식).

새 API 문서 페이지를 추가한 후에는 전역 내비게이션에 항목을 추가하세요.

페이지 메타데이터#

새 페이지를 생성할 때 일관성을 위해 다음 지침을 따르는 description 메타데이터 필드를 프론트매터에 포함하세요:

• "REST API to"로 시작

• 사용자가 API로 할 수 있는 작업을 설명하는 동사 사용

• -ing로 끝나는 단어 사용 금지

• 한 문장으로 유지, 가능하면 100자 이하

• 마침표로 끝내기

예를 들면:

---
stage: Example Stage
group: Example Group
info: To determine the technical writer assigned to the Stage/Group associated with this page, see <https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments>
description: REST API to create, update, and delete issues.
title: Example page title
---

추가 예시:

• description: REST API to retrieve CI/CD job details, retry and cancel jobs, run manual jobs, and access job logs.

• description: REST API to create, manage, and monitor CI/CD pipelines.

API 토픽 템플릿#

다음 템플릿을 시작점으로 사용하세요. 테이블에서 필수 속성을 먼저 나열하세요.

## API name

<details class="history-toggle"><summary>히스토리</summary><ul><li>History note.</li></ul></details>

Use this API to ...

### Operation title

<details class="history-toggle"><summary>히스토리</summary><ul><li>History note.</li></ul></details>

Description of the operation.

```plaintext
METHOD /api/v4/endpoint

Supported attributes:

If successful, returns <status_code> and the following response attributes:

Example request:

curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/endpoint?parameters"

Example response:

[
  {
  }
]

## 히스토리

새로운 또는 업데이트된 API 호출을 설명하기 위해 [히스토리](/19.1/development/documentation/styleguide/availability_details/#history)를 추가하세요.

개별 속성에 대한 히스토리를 추가하려면 섹션의 히스토리에 포함하세요. 예를 들면:

Edit a widget#

히스토리

• widget_message introduced in GitLab 14.3.

API 또는 속성이 기능 플래그 뒤에 배포된 경우, 히스토리에 [기능 플래그 정보를 포함](/19.1/development/documentation/feature_flags/)하세요.

## 사용 중단

API 엔드포인트의 사용 중단을 문서화하려면 [페이지 또는 토픽 사용 중단](/19.1/development/documentation/styleguide/deprecations_and_removals/) 단계를 따르세요.

속성을 사용 중단하려면:

- 히스토리 노트를 추가합니다.

히스토리

• widget_name deprecated in GitLab 14.7.

- 설명에 인라인 사용 중단 텍스트를 추가합니다.

사용 중단을 널리 알리려면 [REST API 사용 중단 페이지를 업데이트](/19.1/api/rest/deprecations/)하세요.

## API 소개

각 API는 하나 이상의 작업으로 구성됩니다. 토픽의 시작 부분에 API의 모든 작업에 적용되는 정보와 관련 기능에 대한 짧은 설명을 포함하세요.

일관성을 위해, 소개를 `Use this API to {verb} + [{feature}](link/to/UI/docs).` 형식으로 시작하세요.
이를 통해 사용자를 더 많은 컨텍스트를 포함할 수 있는 관련 문서로 안내할 수 있습니다.

예를 들면:

- `Use this API to manage [Git branches](path/to/file).`

- `Use this API to interact with the [Maven package manager client](path/to/file).`

- `Use this API to interact with namespaces, a special resource category used to organize users and groups. For more information, see [namespaces](path/to/file).`

## 작업 제목

작업 제목은 동사로 시작하세요. 일관성을 위해 HTTP 메서드에 따라 다음 동사를 사용하세요:

| HTTP 메서드 | 동사 | 대안 | 예시 |
| --- | --- | --- | --- |
| GET (복수) | List all |  | List all group access tokens |
| GET (단수) | Retrieve | Download | Retrieve a group audit event, Download a dependency list export |
| POST | Create | Add | Create a repository branch, Add a new emoji reaction |
| PUT | Update | Replace | Update a project topic |
| PATCH | Update | Modify | Update a freeze period, Modify an existing commit thread note |
| DELETE | Delete |  | Delete a feature |

가능하면 권장 동사를 사용하세요. 대안은 특정 맥락에서 필요할 수 있지만, 일관성을 유지하기 위해 최소한으로 사용하세요.

## 작업 설명

각 작업에는 용도를 설명하고 중요한 정보를 강조하는 짧은 설명이 포함되어야 합니다.
가능하면 첫 번째 문장이 작업의 제목을 넓게 반복하도록 작성하세요. 예를 들면:

- `List all project access tokens` -> `Lists all project access tokens.`

- `Delete an SSH key` -> `Deletes an SSH key from your user account.`

- `Retrieve an enterprise user` -> `Retrieves details on a specified enterprise user.`

## 요청 속성

작업에서 요청 속성을 문서화해야 합니다. 테이블 및 속성 설명을 작성할 때:

- 속성 테이블에 다음 칼럼 이름을 사용하세요.

- 경로 속성을 먼저 나열하고, 필수 속성을 나열한 다음, 알파벳순으로 정렬하세요.

- 속성 이름을 백틱(```)을 사용한 코드 블록에 넣으세요.

- 속성에 특정한 티어 또는 오퍼링 정보는 설명에 문서화하세요.

속성이 Premium에서 사용 가능한 경우, Ultimate에서도 사용 가능하다고 언급하세요.

- 가능하면 이 티어 및 오퍼링 정보를 결합하세요. 예: `GitLab Self-Managed, Premium and Ultimate only.`

렌더링 예시:

| Attribute | Type | Required | Description |
| --- | --- | --- | --- |
| title | string | Yes | Title of the issue. GitLab Self-Managed only. |
| assignee_ids | integer array | No | IDs of the users to assign the issue to. Ultimate only. |
| confidential | boolean | No | Sets the issue to confidential. Default is false. |

속성 설명 작성에 대한 정보는 [GraphQL API 설명 스타일 가이드](/19.1/development/api_graphql_styleguide/#description-style-guide)를 참조하세요.

### 조건부 필수 속성

속성이 다른 항목과 관련된 경우 속성 설명에 이를 표시하세요.

일반적으로 두 속성 중 하나가 필수이거나 속성을 별도로 활성화하고 구성해야 하는 경우 이런 상황이 발생합니다.

먼저 속성 자체를 정의한 다음 요구 사항을 언급하세요. 다음 형식을 사용하세요:

Required if attribute1 is true.

예를 들면:

| Attribute | Type | Required | Description |
| --- | --- | --- | --- |
| include_saml_users | boolean | Conditional | If true, returns users with a SAML identity. Required if include_service_accounts is false. |
| include_service_accounts | boolean | Conditional | If true, returns service account users. Required if include_saml_users is false. |
| a_related_setting | boolean | Conditional | If true, does something else. Required if include_saml_users is true. |

## 응답 속성

때로는 작업에서 응답 속성을 문서화해야 할 수도 있습니다. 이는 보통 필수 사항은 아닙니다.
테이블 및 속성 설명을 작성할 때:

- 속성 테이블에 다음 칼럼 이름을 사용하세요.

- 테이블을 알파벳순으로 정렬하세요.

- 속성 이름을 백틱(```)을 사용한 코드 블록에 넣으세요.

- 객체 또는 배열을 설명하는 경우 점 표기법을 사용하여 하위 속성을 나타내세요. 예: `project.name` 또는 `projects[].name`.

- 속성에 특정한 티어 또는 오퍼링 정보는 설명에 문서화하세요.

속성이 Premium에서 사용 가능한 경우, Ultimate에서도 사용 가능하다고 언급하세요.

- 가능하면 이 티어 및 오퍼링 정보를 결합하세요. 예: `GitLab Self-Managed, Premium and Ultimate only.`

`status code`를 관련 [HTTP 상태 코드](/19.1/api/rest/troubleshooting/#status-codes)로 대체하여 다음 문장으로 설명을 시작하세요:

If successful, returns 200 OK and the following response attributes:

렌더링 예시:

| Attribute | Type | Description |
| --- | --- | --- |
| assignee_ids | integer array | IDs of the users to assign the issue to. Premium and Ultimate only. |
| commits | object array | Commits in the merge request diff. |
| commits[].id | string | ID of the commit. |

속성 설명 작성에 대한 정보는 [GraphQL API 설명 스타일 가이드](/19.1/development/api_graphql_styleguide/#description-style-guide)를 참조하세요.

## cURL 명령어

- 엔드포인트로 `https://gitlab.example.com/api/v4/`를 사용하세요.

- 필요한 경우 개인 액세스 토큰을 사용하세요: `<your_access_token>`.

- 항상 요청 메서드를 먼저 입력하세요. `GET`을 포함한 모든 HTTP 메서드에 대해 `--request `를 지정하세요.

- 가독성을 위해 긴 옵션 이름을 사용하세요(`-H` 대신 `--header`). ([`scripts/lint-doc.sh`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/scripts/lint-doc.sh)에서 테스트됨.)

- `--url` 매개변수로 URL을 선언하고, URL을 큰따옴표(`"`)로 감싸세요.

- 개인 액세스 토큰을 사용하는 예시를 선호하며, 사용자명과 패스워드 데이터는 전달하지 마세요.

- 가독성을 위해 긴 단일 행 명령을 여러 줄로 나누려면 `\` 문자와 들여쓰기를 사용하세요.

| 메서드 | 설명 |
| --- | --- |
| --header "PRIVATE-TOKEN: <your_access_token>" | 인증이 필요할 때마다 이 메서드를 그대로 사용하세요. |
| --request GET | 기존 객체를 조회할 때 이 메서드를 사용하세요. |
| --request POST | 새 객체를 생성할 때 이 메서드를 사용하세요. |
| --request PUT | 기존 객체를 업데이트할 때 이 메서드를 사용하세요. |
| --request DELETE | 기존 객체를 제거할 때 이 메서드를 사용하세요. |

## cURL 예시

다음 섹션에는 API 문서에서 사용할 수 있는 [cURL](https://curl.se/) 예시 세트가 포함되어 있습니다.

실제 사용자, URL 또는 토큰 정보를 사용하지 마세요. 문서화를 위해 [가상 사용자 정보](/19.1/development/documentation/styleguide/#fake-user-information),
[가상 URL](/19.1/development/documentation/styleguide/#fake-urls), [가상 토큰](/19.1/development/documentation/styleguide/#fake-tokens)에 관한 스타일 가이드 섹션을 참조하세요.

### 간단한 cURL 명령어

그룹의 세부 정보를 가져옵니다:

curl --request GET
--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를 사용하여 데이터 POST

`--request POST`를 사용하고 URI에 매개변수를 추가하는 대신, cURL의 `--data` 옵션을 사용할 수 있습니다.
아래 예시는 인증된 사용자의 네임스페이스 아래에 새 프로젝트 `foo`를 생성합니다.

curl --data "name=foo"
--header "PRIVATE-TOKEN: <your_access_token>"
--url "https://gitlab.example.com/api/v4/projects"

### cURL의 --data-urlencode를 사용하여 데이터 POST

URL 인코딩이 필요한 특수 문자가 포함된 데이터의 경우 `--data-urlencode`를 사용하세요.

다음의 경우에 이 옵션을 사용할 수 있습니다:

- 코드 블록 또는 특수 형식이 포함된 Markdown 콘텐츠.

- `+`, `.`, 또는 `*`가 포함된 정규 표현식.

- 따옴표, 앰퍼샌드 또는 기타 예약된 URL 문자가 포함된 텍스트.

- 특수 문자가 포함될 수 있는 파일 콘텐츠.

특수 문자가 없는 영숫자 데이터의 경우 [`--data`](/19.1/development/documentation/restful_api_styleguide/#post-data-using-curls---data)를 대신 사용하세요.

특수 문자가 있는 속성의 경우:

curl --request POST
--header "PRIVATE-TOKEN: <your_access_token>"
--data-urlencode "description=Fix issue with 'quotes' & ampersands"
--url "https://gitlab.example.com/api/v4/projects/1/issues"

정규 표현식 패턴이 있는 콘텐츠의 경우:

curl --request DELETE
--header "PRIVATE-TOKEN: <your_access_token>"
--data-urlencode "name_regex_delete=dev-.+"
--url "https://gitlab.example.com/api/v4/projects/5/registry/repositories/2/tags"

파일의 콘텐츠의 경우 `attribute@filename`을 사용하세요:

curl --request POST
--header "PRIVATE-TOKEN: <your_access_token>"
--data-urlencode "title=API documentation update"
--data-urlencode "content@content.md"
--url "https://gitlab.example.com/api/v4/projects/1/wikis"

### JSON 콘텐츠를 사용하여 데이터 POST

이 예시는 새 그룹을 생성합니다. 단일(`'`) 따옴표와 이중(`"`) 따옴표의 사용에 주의하세요.

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를 사용하여 데이터 POST

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 공개 키를 추가합니다. 이 작업은 관리자 액세스가 필요합니다.

### 특수 문자 이스케이프

공백이나 슬래시(`/`)는 경우에 따라 오류를 발생시킬 수 있으므로 가능한 경우 이스케이프 처리해야 합니다.
아래 예시에서는 제목에 공백이 포함된 새 이슈를 생성합니다.
공백이 ASCII 코드 `%20`을 사용하여 이스케이프되는 방법을 확인하세요.

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"