REST API 리소스 문서화

REST API 리소스는 여기의 Markdown에서 문서화됩니다. 각 리소스는 자체 Markdown 파일을 가지며, 이 파일은 api_resources.md에서 링크됩니다.

Markdown을 수정할 때 해당 리소스에 대한 OpenAPI 정의도 업데이트하십시오. 리소스에 대한 OpenAPI 정의가 없는 경우 생성을 고려해보십시오. 최신 OpenAPI 3.0.x 사양과 일치시키십시오. (더 많은 정보는 이곳의 토론을 참조하십시오.)

리소스에 대한 Markdown 문서에서 (또는 엔드포인트로 알려진) 다음 사항을 고려하십시오:

  • 각 메서드는 REST API 요청을 가져야합니다. 예를 들어: 

    GET /api/v4/projects/:id/repository/branches
  • 각 메서드는 속성의 상세한 설명을 가져야합니다.
  • 각 메서드는 cURL 예제를 가져야합니다.
  • 각 메서드는 응답 본문의 상세한 설명을 가져야합니다.
  • 각 메서드는 응답 본문 예제( JSON 형식)를 가져야합니다.
  • 특정 구독 티어에서만 사용할 수있는 속성이있는 경우 설명에 적절한 티어를 추가하십시오. 특정 속성이 Premium에만 해당하는 경우에도 궁금 확인을 포함하여 궁극적으로도 사용할 수 있음을 명시하십시오.
  • 특정 제공에서만 사용할 수있는 속성이 있는 경우 설명에 해당 제공물을 추가하십시오. 속성의 설명에서 제공과 티어를 모두 포함해야하는 경우 이를 결합하십시오. 예: Self-managed, Premium 및 궁극에만 해당함.

새로운 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 또는 속성이 피처 플래그로 배포 된 경우 [피처 플래그 정보](feature_flags.md)를 이력에 포함하십시오. 

## 사용 방법 설명

다음 테이블 헤더를 사용하여 메서드를 설명하십시오. 속성은 먼저 필수 속성으로 정렬한 다음 알파벳순으로 발표해야합니다.

```markdown
| 속성                    | 유형          | 필수  | 설명                                      |
|------------------------------|---------------|----------|-----------------------------------------------------|
| `title`                      | string        | 예      | 이슈의 제목.                                |
| `assignee_ids`               | integer array | 아니오   | 이슈를 할당 할 사용자 ID. 궁극적으로만 가능.    |
| `confidential`               | boolean       | 아니오   | 이슈를 기밀로 설정합니다. 기본값은 `false`입니다. |

렌더링된 예시:

속성 유형 필수 설명
title string 예 이슈의 제목.
assignee_ids integer array 아니오 이슈를 할당 할 사용자 ID. Premium 및 궁극적으로만 가능.
confidential boolean 아니오 이슈를 기밀로 설정합니다. 기본값은 false입니다.

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

응답 본문 설명

다음 문장으로 설명을 시작하십시오. 이때 status code는 관련 [HTTP 상태 코드] (../../api/rest/index.md#status-codes)로 대체하십시오. 

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

다음 테이블 헤더를 사용하여 응답 본문을 설명하십시오. 속성은 항상 백틱 (``)을 사용하여 코드 블록으로 만들어야합니다.

속성이 다른 객체와 같은 복잡한 유형인 경우 점 (.)으로 하위 속성을 표시하십시오. 프로젝트 이름 또는 배열의 경우 projects[].name과 같이 표시하십시오.

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

| 속성                    | 유형          | 설명                                      |
|------------------------------|---------------|-----------------------------------------------------|
| `assignee_ids`               | integer array | 이슈를 할당 할 사용자 ID. Premium 및 궁극적으로만 가능.    |
| `confidential`               | boolean       | 이슈가 기밀인지 여부.                               |
| `title`                      | string        | 이슈의 제목.                                      |

렌더링된 예시:

속성 유형 설명
assignee_ids integer array 이슈를 할당 할 사용자 ID. Premium 및 궁극적으로만 가능.
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 예제

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

caution
실제 사용자, 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"