From 7cd50dad87cf572c92c37d3afbaa1769984a7885 Mon Sep 17 00:00:00 2001 From: Vincent Demeester Date: Tue, 9 Aug 2016 14:50:46 +0200 Subject: [PATCH] Add delete and update API documentation Signed-off-by: Vincent Demeester Upstream-commit: da325c035df5f9d733c130bb57065cad2c9bf7fc Component: engine --- .../reference/api/docker_remote_api_v1.24.md | 91 ++++++++++++++++++- .../reference/api/docker_remote_api_v1.25.md | 86 +++++++++++++++++- 2 files changed, 169 insertions(+), 8 deletions(-) diff --git a/components/engine/docs/reference/api/docker_remote_api_v1.24.md b/components/engine/docs/reference/api/docker_remote_api_v1.24.md index 41f27acaf7..e08b3f1889 100644 --- a/components/engine/docs/reference/api/docker_remote_api_v1.24.md +++ b/components/engine/docs/reference/api/docker_remote_api_v1.24.md @@ -3353,8 +3353,8 @@ List nodes "UpdatedAt": "2016-06-07T20:31:11.999868824Z", "Spec": { "Name": "my-node", - "Role": "MANAGER", - "Availability": "ACTIVE" + "Role": "manager", + "Availability": "active" "Labels": { "foo": "bar" } @@ -3444,8 +3444,8 @@ Return low-level information on the node `id` "UpdatedAt": "2016-06-07T20:31:11.999868824Z", "Spec": { "Name": "my-node", - "Role": "MANAGER", - "Availability": "ACTIVE" + "Role": "manager", + "Availability": "active" "Labels": { "foo": "bar" } @@ -3495,6 +3495,89 @@ Return low-level information on the node `id` } } +**Status codes**: + +- **200** – no error +- **404** – no such node +- **500** – server error + +### Remove a node + + +`DELETE /nodes/` + +Remove a node [`id`] from the Swarm. + +**Example request**: + + DELETE /nodes/24ifsmvkjbyhk HTTP/1.1 + +**Example response**: + + HTTP/1.1 200 OK + Content-Length: 0 + Content-Type: text/plain; charset=utf-8 + +**Query parameters**: + +- **force** - 1/True/true or 0/False/false, Force remove an active node. + Default `false`. + +**Status codes**: + +- **200** – no error +- **404** – no such node +- **500** – server error + +### Update a node + + +`POST /nodes//update` + +Update the node `id`. + +The payload of the `POST` request is the new `NodeSpec` and +overrides the current `NodeSpec` for the specified node. + +If `Availability` or `Role` are omitted, this returns an +error. Any other field omitted resets the current value to either +an empty value or the default cluster-wide value. + +**Example Request** + + POST /nodes/24ifsmvkjbyhk/update?version=8 HTTP/1.1 + Content-Type: application/json + + { + "Availability": "active", + "Name": "node-name", + "Role": "manager", + "Labels": { + "foo": "bar" + } + } + +**Example response**: + + HTTP/1.1 200 OK + Content-Length: 0 + Content-Type: text/plain; charset=utf-8 + +**Query parameters**: + +- **version** – The version number of the node object being updated. This is + required to avoid conflicting writes. + +JSON Parameters: + +- **Annotations** – Optional medata to associate with the service. + - **Name** – User-defined name for the service. + - **Labels** – A map of labels to associate with the service (e.g., + `{"key":"value"[,"key2":"value2"]}`). +- **Role** - Role of the node (worker/manager). +- **Availability** - Availability of the node (active/pause/drain). + + **Status codes**: - **200** – no error diff --git a/components/engine/docs/reference/api/docker_remote_api_v1.25.md b/components/engine/docs/reference/api/docker_remote_api_v1.25.md index b83ce68cdf..2a3fca35dd 100644 --- a/components/engine/docs/reference/api/docker_remote_api_v1.25.md +++ b/components/engine/docs/reference/api/docker_remote_api_v1.25.md @@ -3353,8 +3353,8 @@ List nodes "UpdatedAt": "2016-06-07T20:31:11.999868824Z", "Spec": { "Name": "my-node", - "Role": "MANAGER", - "Availability": "ACTIVE" + "Role": "manager", + "Availability": "active" "Labels": { "foo": "bar" } @@ -3444,8 +3444,8 @@ Return low-level information on the node `id` "UpdatedAt": "2016-06-07T20:31:11.999868824Z", "Spec": { "Name": "my-node", - "Role": "MANAGER", - "Availability": "ACTIVE" + "Role": "manager", + "Availability": "active" "Labels": { "foo": "bar" } @@ -3495,6 +3495,84 @@ Return low-level information on the node `id` } } +**Status codes**: + +- **200** – no error +- **404** – no such node +- **500** – server error + +### Remove a node + + +`DELETE /nodes/` + +Remove a node [`id`] from the Swarm. + +**Example request**: + + DELETE /nodes/24ifsmvkjbyhk HTTP/1.1 + +**Example response**: + + HTTP/1.1 200 OK + Content-Length: 0 + Content-Type: text/plain; charset=utf-8 + +**Status codes**: + +- **200** – no error +- **404** – no such node +- **500** – server error + +### Update a node + + +`POST /nodes//update` + +Update the node `id`. + +The payload of the `POST` request is the new `NodeSpec` and +overrides the current `NodeSpec` for the specified node. + +If `Availability` or `Role` are omitted, this returns an +error. Any other field omitted resets the current value to either +an empty value or the default cluster-wide value. + +**Example Request** + + POST /nodes/24ifsmvkjbyhk/update?version=8 HTTP/1.1 + Content-Type: application/json + + { + "Availability": "active", + "Name": "node-name", + "Role": "manager", + "Labels": { + "foo": "bar" + } + } + +**Example response**: + + HTTP/1.1 200 OK + Content-Length: 0 + Content-Type: text/plain; charset=utf-8 + +**Query parameters**: + +- **version** – The version number of the node object being updated. This is + required to avoid conflicting writes. + +JSON Parameters: + +- **Annotations** – Optional medata to associate with the service. + - **Name** – User-defined name for the service. + - **Labels** – A map of labels to associate with the service (e.g., + `{"key":"value"[,"key2":"value2"]}`). +- **Role** - Role of the node (worker/manager). +- **Availability** - Availability of the node (active/pause/drain). + + **Status codes**: - **200** – no error