From a5f4bba440d7f9ea47046a0a561d49adf0a1e6d4 Mon Sep 17 00:00:00 2001 From: GitLab Bot Date: Wed, 16 Jun 2021 18:25:58 +0000 Subject: Add latest changes from gitlab-org/gitlab@14-0-stable-ee --- .../documentation/restful_api_styleguide.md | 18 ++++++++++++------ 1 file changed, 12 insertions(+), 6 deletions(-) (limited to 'doc/development/documentation/restful_api_styleguide.md') diff --git a/doc/development/documentation/restful_api_styleguide.md b/doc/development/documentation/restful_api_styleguide.md index e05f6760ff1..b3d3e2641b7 100644 --- a/doc/development/documentation/restful_api_styleguide.md +++ b/doc/development/documentation/restful_api_styleguide.md @@ -33,7 +33,8 @@ In the Markdown doc for a resource (AKA endpoint): ## API topic template -The following can be used as a template to get started: +Use the following template to help you get started. Be sure to list any +required attributes first in the table. ````markdown ## Descriptive title @@ -50,8 +51,10 @@ Supported attributes: | Attribute | Type | Required | Description | |:------------|:---------|:---------|:----------------------| -| `attribute` | datatype | yes/no | Detailed description. | -| `attribute` | datatype | yes/no | Detailed description. | +| `attribute` | datatype | **{check-circle}** Yes | Detailed description. | +| `attribute` | datatype | **{dotted-circle}** No | Detailed description. | +| `attribute` | datatype | **{dotted-circle}** No | Detailed description. | +| `attribute` | datatype | **{dotted-circle}** No | Detailed description. | Example request: @@ -147,7 +150,8 @@ This example creates a new group. Be aware of the use of single (`'`) and double (`"`) quotes. ```shell -curl --request POST --header "PRIVATE-TOKEN: " --header "Content-Type: application/json" --data '{"path": "my-group", "name": "My group"}' "https://gitlab.example.com/api/v4/groups" +curl --request POST --header "PRIVATE-TOKEN: " --header "Content-Type: application/json" \ + --data '{"path": "my-group", "name": "My group"}' "https://gitlab.example.com/api/v4/groups" ``` For readability, you can also set up the `--data` by using the following format: @@ -169,7 +173,8 @@ Instead of using JSON or URL-encoding data, you can use `multipart/form-data` wh properly handles data encoding: ```shell -curl --request POST --header "PRIVATE-TOKEN: " --form "title=ssh-key" --form "key=ssh-rsa AAAAB3NzaC1yc2EA..." "https://gitlab.example.com/api/v4/users/25/keys" +curl --request POST --header "PRIVATE-TOKEN: " --form "title=ssh-key" \ + --form "key=ssh-rsa AAAAB3NzaC1yc2EA..." "https://gitlab.example.com/api/v4/users/25/keys" ``` The above example is run by and administrator and will add an SSH public key @@ -195,5 +200,6 @@ exclude specific users when requesting a list of users for a project, you would do something like this: ```shell -curl --request PUT --header "PRIVATE-TOKEN: " --data "skip_users[]=" --data "skip_users[]=" "https://gitlab.example.com/api/v4/projects//users" +curl --request PUT --header "PRIVATE-TOKEN: " --data "skip_users[]=" \ + --data "skip_users[]=" "https://gitlab.example.com/api/v4/projects//users" ``` -- cgit v1.2.3