@@ -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"
In this example we create a new group. Watch carefully the single and double
quotes.
- Include a code block with the query that anyone can include in their
instance of the GraphiQL explorer:
```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"
```
````markdown
```graphql
query{
<insertquerieshere>
}
```
````
#### Post data using form-data
- Tell the user what to do:
Instead of using JSON or urlencode you can use multipart/form-data which
properly handles data encoding:
```markdown
1. Open the GraphiQL explorer tool in the following URL: `https://gitlab.com/-/graphql-explorer`.
1. Paste the `query` listed above into the left window of your GraphiQL explorer tool.
1. Select Play to get the result shown here:
```
```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"
```
- Include a screenshot of the result in the GraphiQL explorer. Follow the naming
convention described in the [Save the image](#save-the-image) section.
- Follow up with an example of what you can do with the output. Make sure the
example is something that readers can do on their own deployments.
- Include a link to the [GraphQL API resources](../../api/graphql/reference/index.md).
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.
### Add the GraphQL example to the Table of Contents
#### Escape special characters
You'll need to open a second MR, against the [GitLab documentation repository](https://gitlab.com/gitlab-org/gitlab-docs/).
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.
We store our Table of Contents in the `default-nav.yaml` file, in the
`content/_data` subdirectory. You can find the GraphQL section under the
following line:
```shell
curl --request POST --header"PRIVATE-TOKEN: <your_access_token>""https://gitlab.example.com/api/v4/projects/42/issues?title=Hello%20Dude"
```yaml
-category_title:GraphQL
```
Use `%2F` for slashes (`/`).
Be aware that CI tests for that second MR will fail with a bad link until the
main MR that adds the new GraphQL page is merged.
#### 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"
