Browse code
Merge pull request #25172 from vdemeester/25153-node-delete-update-api-docs
Add delete and update API documentation
Sebastiaan van Stijn authored on 2016/08/10 15:01:13Showing 2 changed files
| ... | ... |
@@ -3380,8 +3380,8 @@ List nodes |
| 3380 | 3380 |
"UpdatedAt": "2016-06-07T20:31:11.999868824Z", |
| 3381 | 3381 |
"Spec": {
|
| 3382 | 3382 |
"Name": "my-node", |
| 3383 |
- "Role": "MANAGER", |
|
| 3384 |
- "Availability": "ACTIVE" |
|
| 3383 |
+ "Role": "manager", |
|
| 3384 |
+ "Availability": "active" |
|
| 3385 | 3385 |
"Labels": {
|
| 3386 | 3386 |
"foo": "bar" |
| 3387 | 3387 |
} |
| ... | ... |
@@ -3471,8 +3471,8 @@ Return low-level information on the node `id` |
| 3471 | 3471 |
"UpdatedAt": "2016-06-07T20:31:11.999868824Z", |
| 3472 | 3472 |
"Spec": {
|
| 3473 | 3473 |
"Name": "my-node", |
| 3474 |
- "Role": "MANAGER", |
|
| 3475 |
- "Availability": "ACTIVE" |
|
| 3474 |
+ "Role": "manager", |
|
| 3475 |
+ "Availability": "active" |
|
| 3476 | 3476 |
"Labels": {
|
| 3477 | 3477 |
"foo": "bar" |
| 3478 | 3478 |
} |
| ... | ... |
@@ -3528,6 +3528,89 @@ Return low-level information on the node `id` |
| 3528 | 3528 |
- **404** – no such node |
| 3529 | 3529 |
- **500** – server error |
| 3530 | 3530 |
|
| 3531 |
+### Remove a node |
|
| 3532 |
+ |
|
| 3533 |
+ |
|
| 3534 |
+`DELETE /nodes/<id>` |
|
| 3535 |
+ |
|
| 3536 |
+Remove a node [`id`] from the Swarm. |
|
| 3537 |
+ |
|
| 3538 |
+**Example request**: |
|
| 3539 |
+ |
|
| 3540 |
+ DELETE /nodes/24ifsmvkjbyhk HTTP/1.1 |
|
| 3541 |
+ |
|
| 3542 |
+**Example response**: |
|
| 3543 |
+ |
|
| 3544 |
+ HTTP/1.1 200 OK |
|
| 3545 |
+ Content-Length: 0 |
|
| 3546 |
+ Content-Type: text/plain; charset=utf-8 |
|
| 3547 |
+ |
|
| 3548 |
+**Query parameters**: |
|
| 3549 |
+ |
|
| 3550 |
+- **force** - 1/True/true or 0/False/false, Force remove an active node. |
|
| 3551 |
+ Default `false`. |
|
| 3552 |
+ |
|
| 3553 |
+**Status codes**: |
|
| 3554 |
+ |
|
| 3555 |
+- **200** – no error |
|
| 3556 |
+- **404** – no such node |
|
| 3557 |
+- **500** – server error |
|
| 3558 |
+ |
|
| 3559 |
+### Update a node |
|
| 3560 |
+ |
|
| 3561 |
+ |
|
| 3562 |
+`POST /nodes/<id>/update` |
|
| 3563 |
+ |
|
| 3564 |
+Update the node `id`. |
|
| 3565 |
+ |
|
| 3566 |
+The payload of the `POST` request is the new `NodeSpec` and |
|
| 3567 |
+overrides the current `NodeSpec` for the specified node. |
|
| 3568 |
+ |
|
| 3569 |
+If `Availability` or `Role` are omitted, this returns an |
|
| 3570 |
+error. Any other field omitted resets the current value to either |
|
| 3571 |
+an empty value or the default cluster-wide value. |
|
| 3572 |
+ |
|
| 3573 |
+**Example Request** |
|
| 3574 |
+ |
|
| 3575 |
+ POST /nodes/24ifsmvkjbyhk/update?version=8 HTTP/1.1 |
|
| 3576 |
+ Content-Type: application/json |
|
| 3577 |
+ |
|
| 3578 |
+ {
|
|
| 3579 |
+ "Availability": "active", |
|
| 3580 |
+ "Name": "node-name", |
|
| 3581 |
+ "Role": "manager", |
|
| 3582 |
+ "Labels": {
|
|
| 3583 |
+ "foo": "bar" |
|
| 3584 |
+ } |
|
| 3585 |
+ } |
|
| 3586 |
+ |
|
| 3587 |
+**Example response**: |
|
| 3588 |
+ |
|
| 3589 |
+ HTTP/1.1 200 OK |
|
| 3590 |
+ Content-Length: 0 |
|
| 3591 |
+ Content-Type: text/plain; charset=utf-8 |
|
| 3592 |
+ |
|
| 3593 |
+**Query parameters**: |
|
| 3594 |
+ |
|
| 3595 |
+- **version** – The version number of the node object being updated. This is |
|
| 3596 |
+ required to avoid conflicting writes. |
|
| 3597 |
+ |
|
| 3598 |
+JSON Parameters: |
|
| 3599 |
+ |
|
| 3600 |
+- **Annotations** – Optional medata to associate with the service. |
|
| 3601 |
+ - **Name** – User-defined name for the service. |
|
| 3602 |
+ - **Labels** – A map of labels to associate with the service (e.g., |
|
| 3603 |
+ `{"key":"value"[,"key2":"value2"]}`).
|
|
| 3604 |
+- **Role** - Role of the node (worker/manager). |
|
| 3605 |
+- **Availability** - Availability of the node (active/pause/drain). |
|
| 3606 |
+ |
|
| 3607 |
+ |
|
| 3608 |
+**Status codes**: |
|
| 3609 |
+ |
|
| 3610 |
+- **200** – no error |
|
| 3611 |
+- **404** – no such node |
|
| 3612 |
+- **500** – server error |
|
| 3613 |
+ |
|
| 3531 | 3614 |
## 3.7 Swarm |
| 3532 | 3615 |
|
| 3533 | 3616 |
### Initialize a new swarm |
| ... | ... |
@@ -3386,8 +3386,8 @@ List nodes |
| 3386 | 3386 |
"UpdatedAt": "2016-06-07T20:31:11.999868824Z", |
| 3387 | 3387 |
"Spec": {
|
| 3388 | 3388 |
"Name": "my-node", |
| 3389 |
- "Role": "MANAGER", |
|
| 3390 |
- "Availability": "ACTIVE" |
|
| 3389 |
+ "Role": "manager", |
|
| 3390 |
+ "Availability": "active" |
|
| 3391 | 3391 |
"Labels": {
|
| 3392 | 3392 |
"foo": "bar" |
| 3393 | 3393 |
} |
| ... | ... |
@@ -3477,8 +3477,8 @@ Return low-level information on the node `id` |
| 3477 | 3477 |
"UpdatedAt": "2016-06-07T20:31:11.999868824Z", |
| 3478 | 3478 |
"Spec": {
|
| 3479 | 3479 |
"Name": "my-node", |
| 3480 |
- "Role": "MANAGER", |
|
| 3481 |
- "Availability": "ACTIVE" |
|
| 3480 |
+ "Role": "manager", |
|
| 3481 |
+ "Availability": "active" |
|
| 3482 | 3482 |
"Labels": {
|
| 3483 | 3483 |
"foo": "bar" |
| 3484 | 3484 |
} |
| ... | ... |
@@ -3534,6 +3534,84 @@ Return low-level information on the node `id` |
| 3534 | 3534 |
- **404** – no such node |
| 3535 | 3535 |
- **500** – server error |
| 3536 | 3536 |
|
| 3537 |
+### Remove a node |
|
| 3538 |
+ |
|
| 3539 |
+ |
|
| 3540 |
+`DELETE /nodes/<id>` |
|
| 3541 |
+ |
|
| 3542 |
+Remove a node [`id`] from the Swarm. |
|
| 3543 |
+ |
|
| 3544 |
+**Example request**: |
|
| 3545 |
+ |
|
| 3546 |
+ DELETE /nodes/24ifsmvkjbyhk HTTP/1.1 |
|
| 3547 |
+ |
|
| 3548 |
+**Example response**: |
|
| 3549 |
+ |
|
| 3550 |
+ HTTP/1.1 200 OK |
|
| 3551 |
+ Content-Length: 0 |
|
| 3552 |
+ Content-Type: text/plain; charset=utf-8 |
|
| 3553 |
+ |
|
| 3554 |
+**Status codes**: |
|
| 3555 |
+ |
|
| 3556 |
+- **200** – no error |
|
| 3557 |
+- **404** – no such node |
|
| 3558 |
+- **500** – server error |
|
| 3559 |
+ |
|
| 3560 |
+### Update a node |
|
| 3561 |
+ |
|
| 3562 |
+ |
|
| 3563 |
+`POST /nodes/<id>/update` |
|
| 3564 |
+ |
|
| 3565 |
+Update the node `id`. |
|
| 3566 |
+ |
|
| 3567 |
+The payload of the `POST` request is the new `NodeSpec` and |
|
| 3568 |
+overrides the current `NodeSpec` for the specified node. |
|
| 3569 |
+ |
|
| 3570 |
+If `Availability` or `Role` are omitted, this returns an |
|
| 3571 |
+error. Any other field omitted resets the current value to either |
|
| 3572 |
+an empty value or the default cluster-wide value. |
|
| 3573 |
+ |
|
| 3574 |
+**Example Request** |
|
| 3575 |
+ |
|
| 3576 |
+ POST /nodes/24ifsmvkjbyhk/update?version=8 HTTP/1.1 |
|
| 3577 |
+ Content-Type: application/json |
|
| 3578 |
+ |
|
| 3579 |
+ {
|
|
| 3580 |
+ "Availability": "active", |
|
| 3581 |
+ "Name": "node-name", |
|
| 3582 |
+ "Role": "manager", |
|
| 3583 |
+ "Labels": {
|
|
| 3584 |
+ "foo": "bar" |
|
| 3585 |
+ } |
|
| 3586 |
+ } |
|
| 3587 |
+ |
|
| 3588 |
+**Example response**: |
|
| 3589 |
+ |
|
| 3590 |
+ HTTP/1.1 200 OK |
|
| 3591 |
+ Content-Length: 0 |
|
| 3592 |
+ Content-Type: text/plain; charset=utf-8 |
|
| 3593 |
+ |
|
| 3594 |
+**Query parameters**: |
|
| 3595 |
+ |
|
| 3596 |
+- **version** – The version number of the node object being updated. This is |
|
| 3597 |
+ required to avoid conflicting writes. |
|
| 3598 |
+ |
|
| 3599 |
+JSON Parameters: |
|
| 3600 |
+ |
|
| 3601 |
+- **Annotations** – Optional medata to associate with the service. |
|
| 3602 |
+ - **Name** – User-defined name for the service. |
|
| 3603 |
+ - **Labels** – A map of labels to associate with the service (e.g., |
|
| 3604 |
+ `{"key":"value"[,"key2":"value2"]}`).
|
|
| 3605 |
+- **Role** - Role of the node (worker/manager). |
|
| 3606 |
+- **Availability** - Availability of the node (active/pause/drain). |
|
| 3607 |
+ |
|
| 3608 |
+ |
|
| 3609 |
+**Status codes**: |
|
| 3610 |
+ |
|
| 3611 |
+- **200** – no error |
|
| 3612 |
+- **404** – no such node |
|
| 3613 |
+- **500** – server error |
|
| 3614 |
+ |
|
| 3537 | 3615 |
## 3.7 Swarm |
| 3538 | 3616 |
|
| 3539 | 3617 |
### Initialize a new swarm |