InfoGrab DocsInfoGrab Docs

REST API 리소스 문서화

요약

REST API 리소스는 /doc/api 아래에 Markdown으로 문서화됩니다. Markdown 또는 API 코드를 수정할 때는 bin/rake gitlab:openapi:v2:generate 및 bin/rake gitlab:openapi:v3:generate를 실행하여 해당 OpenAPI 정의도 업데이트합니다.

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/marketing/product-and-technical-marketing/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:

Attribute Type Required Description
attribute datatype Yes Detailed description.
attribute datatype No Detailed description.
attribute datatype No Detailed description.
attribute datatype No Detailed description.

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

Attribute Type Description
attribute datatype Detailed description.
attribute datatype Detailed description.

Example request:

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

Example response:

[
  {
  }
]

## 히스토리

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

개별 속성에 대한 히스토리를 추가하려면
속성 설명의 끝에 추가합니다.
예를 들면:

```markdown
| Attribute        | Type   | Required | Description |
|------------------|--------|----------|-------------|
| `widget_message` | string | No       | Message to display on the widget. [Introduced](https://work-item-link) in GitLab 14.3. |

다른 히스토리 항목에도 같은 방식을 사용합니다.

속성을 사용 중단하려면 히스토리 노트와 인라인 히스토리 텍스트를 모두 추가합니다. 자세한 내용은 사용 중단을 참고합니다.

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

사용 중단#

API 엔드포인트의 사용 중단을 문서화하려면 페이지 또는 토픽 사용 중단 단계를 따르세요.

속성을 사용 중단하려면:

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

    <details class="history-toggle"><summary>히스토리</summary><ul><li><code>widget_name</code> <a href="https://work-item-link">deprecated</a> in GitLab 14.7.</li></ul></details>
    
    
  • 설명에 인라인 히스토리 텍스트를 추가합니다.

    | Attribute     | Type   | Required | Description |
    |---------------|--------|----------|-------------|
    | `widget_name` | string | No       | [Deprecated](https://work-item-link) in GitLab 14.7. Use `widget_id` instead. The name of the widget. |
    

사용 중단을 널리 알리려면 REST API 사용 중단 페이지를 업데이트합니다.

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`. |

렌더링 예시:

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 설명 스타일 가이드를 참조합니다.

조건부 필수 속성#

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

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

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

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.

일부 속성은 단일 속성의 값이 아니라 다른 속성 집합에 따라 달라집니다. API가 그룹 중 하나 이상의 속성을 요구하지만 특정 속성을 요구하지는 않을 때 이 패턴을 사용합니다.

다음 형식을 사용합니다.

Required if none of `attribute1`, `attribute2`, or `attribute3` are provided.

예를 들면:

Attribute Type Required Description
target_id string Conditional ID of the target. Required if none of target_name, target_path, or target_url are provided.
target_name string Conditional Name of the target. Required if none of target_id, target_path, or target_url are provided.
target_path string Conditional Path of the target. Required if none of target_id, target_name, or target_url are provided.
target_url string Conditional URL of the target. Required if none of target_id, target_name, or target_path are provided.

응답 속성#

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

  • 속성 테이블에 다음 칼럼 이름을 사용합니다.

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

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

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

  • 속성에 특정한 티어 또는 오퍼링 정보는 설명에 문서화합니다.

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

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

status code를 관련 HTTP 상태 코드로 대체하여 다음 문장으로 설명을 시작합니다:

If successful, returns [`200 OK`](../../api/rest/troubleshooting.md#status-codes) 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. |

렌더링 예시:

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 설명 스타일 가이드를 참조합니다.

cURL 명령어#

  • 엔드포인트로 https://gitlab.example.com/api/v4/를 사용합니다.

  • 필요한 경우 개인 액세스 토큰을 사용합니다: <your_access_token>.

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

  • 가독성을 위해 긴 옵션 이름을 사용합니다(-H 대신 --header). (scripts/lint-doc.sh에서 테스트됨.)

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

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

  • 가독성을 위해 긴 단일 행 명령을 여러 줄로 나누려면 \ 문자와 들여쓰기를 사용합니다.

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

cURL 예시#

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

실제 사용자, URL 또는 토큰 정보를 사용하지 마세요. 문서화를 위해 가상 사용자 정보, 가상 URL, 가상 토큰에 관한 스타일 가이드 섹션을 참조합니다.

간단한 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를 대신 사용합니다.

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

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"

REST API 리소스 문서화

GitLab v19.6
원문 보기

요약

REST API 리소스는 /doc/api 아래에 Markdown으로 문서화됩니다. Markdown 또는 API 코드를 수정할 때는 bin/rake gitlab:openapi:v2:generate 및 bin/rake gitlab:openapi:v3:generate를 실행하여 해당 OpenAPI 정의도 업데이트합니다.

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/marketing/product-and-technical-marketing/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:

Attribute Type Required Description
attribute datatype Yes Detailed description.
attribute datatype No Detailed description.
attribute datatype No Detailed description.
attribute datatype No Detailed description.

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

Attribute Type Description
attribute datatype Detailed description.
attribute datatype Detailed description.

Example request:

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

Example response:

[
  {
  }
]

## 히스토리

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

개별 속성에 대한 히스토리를 추가하려면
속성 설명의 끝에 추가합니다.
예를 들면:

```markdown
| Attribute        | Type   | Required | Description |
|------------------|--------|----------|-------------|
| `widget_message` | string | No       | Message to display on the widget. [Introduced](https://work-item-link) in GitLab 14.3. |

다른 히스토리 항목에도 같은 방식을 사용합니다.

속성을 사용 중단하려면 히스토리 노트와 인라인 히스토리 텍스트를 모두 추가합니다. 자세한 내용은 사용 중단을 참고합니다.

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

사용 중단#

API 엔드포인트의 사용 중단을 문서화하려면 페이지 또는 토픽 사용 중단 단계를 따르세요.

속성을 사용 중단하려면:

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

    <details class="history-toggle"><summary>히스토리</summary><ul><li><code>widget_name</code> <a href="https://work-item-link">deprecated</a> in GitLab 14.7.</li></ul></details>
    
    
  • 설명에 인라인 히스토리 텍스트를 추가합니다.

    | Attribute     | Type   | Required | Description |
    |---------------|--------|----------|-------------|
    | `widget_name` | string | No       | [Deprecated](https://work-item-link) in GitLab 14.7. Use `widget_id` instead. The name of the widget. |
    

사용 중단을 널리 알리려면 REST API 사용 중단 페이지를 업데이트합니다.

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`. |

렌더링 예시:

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 설명 스타일 가이드를 참조합니다.

조건부 필수 속성#

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

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

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

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.

일부 속성은 단일 속성의 값이 아니라 다른 속성 집합에 따라 달라집니다. API가 그룹 중 하나 이상의 속성을 요구하지만 특정 속성을 요구하지는 않을 때 이 패턴을 사용합니다.

다음 형식을 사용합니다.

Required if none of `attribute1`, `attribute2`, or `attribute3` are provided.

예를 들면:

Attribute Type Required Description
target_id string Conditional ID of the target. Required if none of target_name, target_path, or target_url are provided.
target_name string Conditional Name of the target. Required if none of target_id, target_path, or target_url are provided.
target_path string Conditional Path of the target. Required if none of target_id, target_name, or target_url are provided.
target_url string Conditional URL of the target. Required if none of target_id, target_name, or target_path are provided.

응답 속성#

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

  • 속성 테이블에 다음 칼럼 이름을 사용합니다.

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

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

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

  • 속성에 특정한 티어 또는 오퍼링 정보는 설명에 문서화합니다.

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

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

status code를 관련 HTTP 상태 코드로 대체하여 다음 문장으로 설명을 시작합니다:

If successful, returns [`200 OK`](../../api/rest/troubleshooting.md#status-codes) 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. |

렌더링 예시:

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 설명 스타일 가이드를 참조합니다.

cURL 명령어#

  • 엔드포인트로 https://gitlab.example.com/api/v4/를 사용합니다.

  • 필요한 경우 개인 액세스 토큰을 사용합니다: <your_access_token>.

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

  • 가독성을 위해 긴 옵션 이름을 사용합니다(-H 대신 --header). (scripts/lint-doc.sh에서 테스트됨.)

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

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

  • 가독성을 위해 긴 단일 행 명령을 여러 줄로 나누려면 \ 문자와 들여쓰기를 사용합니다.

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

cURL 예시#

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

실제 사용자, URL 또는 토큰 정보를 사용하지 마세요. 문서화를 위해 가상 사용자 정보, 가상 URL, 가상 토큰에 관한 스타일 가이드 섹션을 참조합니다.

간단한 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를 대신 사용합니다.

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

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"