@@ -17,7 +17,7 @@ Each new or updated API endpoint must come with documentation, unless it is inte
The docs should be in the same merge request, or, if strictly necessary,
in a follow-up with the same milestone as the original merge request.
See the [Documentation Style Guide RESTful API section](documentation/styleguide.md#restful-api) for details on documenting API resources in Markdown as well as in OpenAPI definition files.
See the [Documentation Style Guide RESTful API page](documentation/restful_api_styleguide.md) for details on documenting API resources in Markdown as well as in OpenAPI definition files.
In this example we create a new group. Watch carefully the single and double
quotes.
```shell
curl --request POST --header"PRIVATE-TOKEN: <your_access_token>"--header"Content-Type: application/json"--data'{"path": "my-group", "name": "My group"}'"https://gitlab.example.com/api/v4/groups"
```
### Post data using form-data
Instead of using JSON or urlencode you can use multipart/form-data which
properly handles data encoding:
```shell
curl --request POST --header"PRIVATE-TOKEN: <your_access_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
titled `ssh-key` to user's account which has an ID of 25.
### Escape special characters
Spaces or slashes (`/`) may sometimes result to errors, thus it is recommended
to escape them when possible. In the example below we create a new issue which
contains spaces in its title. Observe how spaces are escaped using the `%20`
ASCII code.
```shell
curl --request POST --header"PRIVATE-TOKEN: <your_access_token>""https://gitlab.example.com/api/v4/projects/42/issues?title=Hello%20Dude"
```
Use `%2F` for slashes (`/`).
### Pass arrays to API calls
The GitLab API sometimes accepts arrays of strings or integers. For example, to
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: <your_access_token>"--data"skip_users[]=<user_id>"--data"skip_users[]=<user_id>""https://gitlab.example.com/api/v4/projects/<project_id>/users"
