Expand documentation for Runners API

changelogs/unreleased/docs-42067-document-runner-registration-api.yml

+---
+title: Expand documentation for Runners API
+merge_request: 16484
+author:
+type: other

doc/api/runners.md

@@ -411,3 +411,86 @@ DELETE /projects/:id/runners/:runner_id
 ```
 curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/9/runners/9"
 ```
+
+## Register a new Runner
+
+Register a new Runner for the instance.
+
+```
+POST /runners
+```
+
+| Attribute   | Type    | Required | Description         |
+|-------------|---------|----------|---------------------|
+| `token`     | string  | yes      | Registration token ([Read how to obtain a token](../ci/runners/README.md)) |
+| `description`| string | no       | Runner's description|
+| `info`       | hash   | no       | Runner's metadata   |
+| `active`     | boolean| no       | Whether the Runner is active   |
+| `locked`     | boolean| no       | Whether the Runner should be locked for current project |
+| `run_untagged` | boolean | no | Whether the Runner should handle untagged jobs |
+| `tag_list` | Array[String] | no | List of Runner's tags |
+| `maximum_timeout` | integer | no | Maximum timeout set when this Runner will handle the job |
+
+```
+curl --request POST "https://gitlab.example.com/api/v4/runners" --form "token=ipzXrMhuyyJPifUt6ANz" --form "description=test-1-20150125-test" --form "tag_list=ruby,mysql,tag1,tag2"
+```
+
+Response:
+
+| Status    | Description                     |
+|-----------|---------------------------------|
+| 201       | Runner was created              |
+
+Example response:
+
+```json
+{
+    "id": "12345",
+    "token": "6337ff461c94fd3fa32ba3b1ff4125"
+}
+```
+
+## Delete a registered Runner
+
+Deletes a registed Runner.
+
+```
+DELETE /runners
+```
+
+| Attribute   | Type    | Required | Description         |
+|-------------|---------|----------|---------------------|
+| `token`     | string  | yes      | Runner's authentication token  |
+
+```
+curl --request DELETE "https://gitlab.example.com/api/v4/runners" --form "token=ebb6fc00521627750c8bb750f2490e"
+```
+
+Response:
+
+| Status    | Description                     |
+|-----------|---------------------------------|
+| 204       | Runner was deleted              |
+
+## Verify authentication for a registered Runner
+
+Validates authentication credentials for a registered Runner.
+
+```
+POST /runners/verify
+```
+
+| Attribute   | Type    | Required | Description         |
+|-------------|---------|----------|---------------------|
+| `token`     | string  | yes      | Runner's authentication token  |
+
+```
+curl --request POST "https://gitlab.example.com/api/v4/runners/verify" --form "token=ebb6fc00521627750c8bb750f2490e"
+```
+
+Response:
+
+| Status    | Description                     |
+|-----------|---------------------------------|
+| 200       | Credentials are valid           |
+| 403       | Credentials are invalid         |