@@ -17,7 +17,7 @@ Each new or updated API endpoint must come with documentation, unless it is inte
...
@@ -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,
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.
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"
- Include a code block with the query that anyone can include in their
In this example we create a new group. Watch carefully the single and double
instance of the GraphiQL explorer:
quotes.
```shell
````markdown
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"
```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
```markdown
properly handles data encoding:
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
- Include a screenshot of the result in the GraphiQL explorer. Follow the naming
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"
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
### Add the GraphQL example to the Table of Contents
titled `ssh-key` to user's account which has an ID of 25.
#### 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
We store our Table of Contents in the `default-nav.yaml` file, in the
to escape them when possible. In the example below we create a new issue which
`content/_data` subdirectory. You can find the GraphQL section under the
contains spaces in its title. Observe how spaces are escaped using the `%20`
following line:
ASCII code.
```shell
```yaml
curl --request POST --header"PRIVATE-TOKEN: <your_access_token>""https://gitlab.example.com/api/v4/projects/42/issues?title=Hello%20Dude"
-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
And that's all you need!
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"
