REST API 리소스 문서화

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

Markdown을 수정할 때, 리소스에 대한 해당 OpenAPI 정의도 업데이트하세요. 만약 존재하지 않는 경우, 하나를 작성하는 것을 고려하세요. 최신 OpenAPI 3.0.x 사양에 맞춰야 합니다. (자세한 정보는 이 이슈에서 논의된 내용을 참조하세요.)

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

  • 모든 메서드는 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`              | datatype | 예     | 상세 설명입니다.       |
| `attribute`              | datatype | 아니오   | 상세 설명입니다.       |
| `attribute`              | datatype | 아니오   | 상세 설명입니다.       |
| `attribute`              | datatype | 아니오   | 상세 설명입니다.       |

성공하면 [`<status_code>`](rest/troubleshooting.md#status-codes)를 반환하고 다음의 응답 속성을 포함합니다:

| 속성                     | 형식     | 설명                 |
|--------------------------|----------|---------------------|
| `attribute`              | datatype | 상세 설명입니다.       |
| `attribute`              | datatype | 상세 설명입니다.       |

예시 요청:

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

예시 응답:

```json
[
  {
  }
]
```

역사

새로운 API 호출에 대한 설명을 추가하려면 역사를 추가하세요.

개별 속성에 대한 역사를 추가하려면, 해당 섹션의 역사에 포함하세요. 예를 들어:

위젯 편집

API 또는 속성이 기능 플래그 뒤에 배포된 경우, 기능 플래그 정보를 포함하세요 히스토리에.

사용 중지

API 엔드포인트의 사용 중지를 문서화하려면 다음 단계를 따르세요. 페이지 또는 주제 사용 중지하기.

속성을 사용 중지하려면:

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

    > - `widget_name`는 GitLab 14.7에서 [사용 중지되었습니다](https://link-to-issue).

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

    | Attribute     | Type   | Required | Description |
|---------------|--------|----------|-------------|
| `widget_name` | string | No       | GitLab 14.7에서 [사용 중지](https://link-to-issue)되었으며 15.4에서 제거될 예정입니다. 대신 `widget_id`를 사용하세요. 위젯의 이름입니다. |

사용 중지를 널리 알리거나, 파괴적인 변경 사항인 경우, REST API 사용 중지 및 제거 페이지를 업데이트하세요.

메소드 설명

다음 표 헤더를 사용하여 메소드를 설명하세요. 속성은 항상 백틱(`)을 사용하여 코드 블록에 있어야 합니다.

표는 필수 속성을 먼저 정렬한 다음, 알파벳순으로 정렬하세요.

| Attribute                    | Type          | Required | Description                                         |
|------------------------------|---------------|----------|-----------------------------------------------------|
| `title`                      | string        | Yes      | 이슈의 제목입니다.                                 |
| `assignee_ids`               | integer array | No       | 이슈를 할당할 사용자 ID. Ultimate만 해당. |
| `confidential`               | boolean       | No       | 이슈를 비밀로 설정합니다. 기본값은 `false`입니다. |

렌더링된 예시:

Attribute Type Required Description
title string Yes 이슈의 제목입니다.
assignee_ids integer array No 이슈를 할당할 사용자 ID. Premium 및 Ultimate만 해당.
confidential boolean No 이슈를 비밀로 설정합니다. 기본값은 false입니다.

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

조건부 필수 속성

하나 또는 두 개의 속성이 API 요청을 만들기 위해 필수인 경우:

  1. Required 열에 Conditionally를 추가하세요.

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

    API 호출에 `attribute1` 또는 `attribute2` 중 적어도 하나가 포함되어야 합니다. 필요시 둘 다 사용할 수 있습니다.

예를 들어:

Attribute Type Required Description
include_saml_users boolean Conditionally SAML 아이디를 가진 사용자를 포함합니다. include_saml_users 또는 include_service_accounts 중 적어도 하나는 true이어야 합니다. 필요시 둘 다 사용할 수 있습니다.
include_service_accounts boolean Conditionally 서비스 계정 사용자를 포함합니다. include_saml_users 또는 include_service_accounts 중 적어도 하나는 true이어야 합니다. 필요시 둘 다 사용할 수 있습니다.

응답 본문 설명

다음 문장으로 설명을 시작합니다. status code를 관련 HTTP 상태 코드로 교체합니다. 예를 들어:

성공하면 [`200 OK`](../../api/rest/troubleshooting.md#status-codes)를 반환하며
다음 응답 속성이 포함됩니다:

응답 본문을 설명하기 위해 다음 표 헤더를 사용합니다. 속성은 항상 코드 블록에서 백틱(`)을 사용해야 합니다.

속성이 복합 타입인 경우, 다른 객체처럼 하위 속성을 점(.)으로 나타냅니다. 예: project.name 또는 배열의 경우 projects[].name.

표는 알파벳순으로 정렬합니다.

| Attribute                    | Type          | Description                               |
|------------------------------|---------------|-------------------------------------------|
| `assignee_ids`               | integer array | 문제를 할당할 사용자 ID. Premium 및 Ultimate 전용. |
| `confidential`               | boolean       | 문제가 기밀인지 여부.                      |
| `title`                      | string        | 문제의 제목.                               |

렌더링된 예시:

Attribute Type Description
assignee_ids integer array 문제를 할당할 사용자 ID. Premium 및 Ultimate 전용.
confidential boolean 문제가 기밀인지 여부.
title string 문제의 제목.

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

cURL 명령어

  • 엔드포인트로 https://gitlab.example.com/api/v4/를 사용합니다.
  • 필요한 곳에 이 개인 액세스 토큰을 사용합니다: <your_access_token>.
  • 요청을 먼저 작성하세요. GET이 기본값이므로 포함할 필요가 없습니다.
  • 가독성을 위해 긴 옵션 이름(--header 대신 -H)을 사용합니다. (Tested in 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를 사용하여 데이터 게시

--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"
}'

폼 데이터 사용하여 데이터 게시

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"