kotovalexarian-likes-gitlab
/
gitlab-org--gitlab-foss
1
0
Fork 0
Code Releases Activity

Add latest changes from gitlab-org/gitlab@master

This commit is contained in:
GitLab Bot 2022-05-07 09:07:35 +00:00
parent d8f08f84bd
commit d30b815079
1 changed files with 48 additions and 12 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

60
doc/development/documentation/restful_api_styleguide.md
View File

@ -26,11 +26,12 @@ In the Markdown doc for a resource (AKA endpoint):
GET /projects/:id/repository/branches
```
- Every method must have a detailed [description of the parameters](#method-description).
- Every method must have a detailed [description of the attributes](#method-description).
- Every method must have a cURL example.
- Every method must have a response body (in JSON format).
- Every method must have a detailed [description of the response body](#response-body-description).
- Every method must have a response body example (in JSON format).
- If an attribute is available only to higher level tiers than the other
parameters, add the appropriate inline [tier badge](styleguide/index.md#product-tier-badges).
attributes, add the appropriate inline [tier badge](styleguide/index.md#product-tier-badges).
Put the badge in the **Attribute** column, like the
`**(<tier>)**` code in the following template.
@ -59,6 +60,13 @@ Supported attributes:
| `attribute` | datatype | **{dotted-circle}** No | Detailed description. |
| `attribute` | datatype | **{dotted-circle}** No | Detailed description. |
Response body attributes:
| Attribute | Type | Description |
|:-------------------------|:---------|:----------------------|
| `attribute` | datatype | Detailed description. |
| `attribute` **(<tier>)** | datatype | Detailed description. |
Example request:
```shell
@ -86,23 +94,51 @@ always be in code blocks using backticks (`` ` ``).
Sort the table by required attributes first, then alphabetically.
```markdown
| Attribute | Type | Required | Description |
|:-----------------------------|:--------------|:-----------------------|:-----------------------------------------------------|
| Attribute | Type | Required | Description |
|:-----------------------------|:--------------|:-----------------------|:----------------------------------------------------|
| `title` | string | **{check-circle}** Yes | Title of the issue. |
| `assignee_ids` **(PREMIUM)** | integer array | **{dotted-circle}** No | IDs of the users to assign the issue to. |
| `assignee_ids` **(PREMIUM)** | integer array | **{dotted-circle}** No | IDs of the users to assign the issue to. |
| `confidential` | boolean | **{dotted-circle}** No | Sets the issue to confidential. Default is `false`. |
```
Rendered example:
| Attribute | Type | Required | Description |
|:-----------------------------|:--------------|:-----------------------|:-----------------------------------------------------|
| Attribute | Type | Required | Description |
|:-----------------------------|:--------------|:-----------------------|:----------------------------------------------------|
| `title` | string | **{check-circle}** Yes | Title of the issue. |
| `assignee_ids` **(PREMIUM)** | integer array | **{dotted-circle}** No | IDs of the users to assign the issue to. |
| `assignee_ids` **(PREMIUM)** | integer array | **{dotted-circle}** No | IDs of the users to assign the issue to. |
| `confidential` | boolean | **{dotted-circle}** No | Sets the issue to confidential. Default is `false`. |
For information about writing attribute descriptions, see the [GraphQL API description style guide](../api_graphql_styleguide.md#description-style-guide).
## Response body description
Use the following table headers to describe the response bodies. Attributes should
always be in code blocks using backticks (`` ` ``).
If the attribute is a complex type, like another object, represent sub-attributes
with dots (`.`), like `project.name` or `projects[].name` in case of an array.
Sort the table alphabetically.
```markdown
| Attribute | Type | Description |
|:-----------------------------|:--------------|:------------------------------------------|
| `assignee_ids` **(PREMIUM)** | integer array | IDs of the users to assign the issue to. |
| `confidential` | boolean | Whether the issue is confidential or not. |
| `title` | string | Title of the issue. |
```
Rendered example:
| Attribute | Type | Description |
|:-----------------------------|:--------------|:------------------------------------------|
| `assignee_ids` **(PREMIUM)** | integer array | IDs of the users to assign the issue to. |
| `confidential` | boolean | Whether the issue is confidential or not. |
| `title` | string | Title of the issue. |
For information about writing attribute descriptions, see the [GraphQL API description style guide](../api_graphql_styleguide.md#description-style-guide).
## cURL commands
- Use `https://gitlab.example.com/api/v4/` as an endpoint.
@ -116,9 +152,9 @@ For information about writing attribute descriptions, see the [GraphQL API descr
| Methods | Description |
|:------------------------------------------------|:-------------------------------------------------------|
| `--header "PRIVATE-TOKEN: <your_access_token>"` | Use this method as is, whenever authentication needed. |
| `--request POST` | Use this method when creating new objects |
| `--request PUT` | Use this method when updating existing objects |
| `--request DELETE` | Use this method when removing existing objects |
| `--request POST` | Use this method when creating new objects. |
| `--request PUT` | Use this method when updating existing objects. |
| `--request DELETE` | Use this method when removing existing objects. |
## cURL Examples