Browse code
Add delete and update API documentation
Signed-off-by: Vincent Demeester <vincent@sbr.pm>
Vincent Demeester authored on 2016/08/09 21:50:46Showing 2 changed files
| ... | ... |
@@ -3353,8 +3353,8 @@ List nodes |
| 3353 | 3353 |
"UpdatedAt": "2016-06-07T20:31:11.999868824Z", |
| 3354 | 3354 |
"Spec": {
|
| 3355 | 3355 |
"Name": "my-node", |
| 3356 |
- "Role": "MANAGER", |
|
| 3357 |
- "Availability": "ACTIVE" |
|
| 3356 |
+ "Role": "manager", |
|
| 3357 |
+ "Availability": "active" |
|
| 3358 | 3358 |
"Labels": {
|
| 3359 | 3359 |
"foo": "bar" |
| 3360 | 3360 |
} |
| ... | ... |
@@ -3444,8 +3444,8 @@ Return low-level information on the node `id` |
| 3444 | 3444 |
"UpdatedAt": "2016-06-07T20:31:11.999868824Z", |
| 3445 | 3445 |
"Spec": {
|
| 3446 | 3446 |
"Name": "my-node", |
| 3447 |
- "Role": "MANAGER", |
|
| 3448 |
- "Availability": "ACTIVE" |
|
| 3447 |
+ "Role": "manager", |
|
| 3448 |
+ "Availability": "active" |
|
| 3449 | 3449 |
"Labels": {
|
| 3450 | 3450 |
"foo": "bar" |
| 3451 | 3451 |
} |
| ... | ... |
@@ -3501,6 +3501,89 @@ Return low-level information on the node `id` |
| 3501 | 3501 |
- **404** – no such node |
| 3502 | 3502 |
- **500** – server error |
| 3503 | 3503 |
|
| 3504 |
+### Remove a node |
|
| 3505 |
+ |
|
| 3506 |
+ |
|
| 3507 |
+`DELETE /nodes/<id>` |
|
| 3508 |
+ |
|
| 3509 |
+Remove a node [`id`] from the Swarm. |
|
| 3510 |
+ |
|
| 3511 |
+**Example request**: |
|
| 3512 |
+ |
|
| 3513 |
+ DELETE /nodes/24ifsmvkjbyhk HTTP/1.1 |
|
| 3514 |
+ |
|
| 3515 |
+**Example response**: |
|
| 3516 |
+ |
|
| 3517 |
+ HTTP/1.1 200 OK |
|
| 3518 |
+ Content-Length: 0 |
|
| 3519 |
+ Content-Type: text/plain; charset=utf-8 |
|
| 3520 |
+ |
|
| 3521 |
+**Query parameters**: |
|
| 3522 |
+ |
|
| 3523 |
+- **force** - 1/True/true or 0/False/false, Force remove an active node. |
|
| 3524 |
+ Default `false`. |
|
| 3525 |
+ |
|
| 3526 |
+**Status codes**: |
|
| 3527 |
+ |
|
| 3528 |
+- **200** – no error |
|
| 3529 |
+- **404** – no such node |
|
| 3530 |
+- **500** – server error |
|
| 3531 |
+ |
|
| 3532 |
+### Update a node |
|
| 3533 |
+ |
|
| 3534 |
+ |
|
| 3535 |
+`POST /nodes/<id>/update` |
|
| 3536 |
+ |
|
| 3537 |
+Update the node `id`. |
|
| 3538 |
+ |
|
| 3539 |
+The payload of the `POST` request is the new `NodeSpec` and |
|
| 3540 |
+overrides the current `NodeSpec` for the specified node. |
|
| 3541 |
+ |
|
| 3542 |
+If `Availability` or `Role` are omitted, this returns an |
|
| 3543 |
+error. Any other field omitted resets the current value to either |
|
| 3544 |
+an empty value or the default cluster-wide value. |
|
| 3545 |
+ |
|
| 3546 |
+**Example Request** |
|
| 3547 |
+ |
|
| 3548 |
+ POST /nodes/24ifsmvkjbyhk/update?version=8 HTTP/1.1 |
|
| 3549 |
+ Content-Type: application/json |
|
| 3550 |
+ |
|
| 3551 |
+ {
|
|
| 3552 |
+ "Availability": "active", |
|
| 3553 |
+ "Name": "node-name", |
|
| 3554 |
+ "Role": "manager", |
|
| 3555 |
+ "Labels": {
|
|
| 3556 |
+ "foo": "bar" |
|
| 3557 |
+ } |
|
| 3558 |
+ } |
|
| 3559 |
+ |
|
| 3560 |
+**Example response**: |
|
| 3561 |
+ |
|
| 3562 |
+ HTTP/1.1 200 OK |
|
| 3563 |
+ Content-Length: 0 |
|
| 3564 |
+ Content-Type: text/plain; charset=utf-8 |
|
| 3565 |
+ |
|
| 3566 |
+**Query parameters**: |
|
| 3567 |
+ |
|
| 3568 |
+- **version** – The version number of the node object being updated. This is |
|
| 3569 |
+ required to avoid conflicting writes. |
|
| 3570 |
+ |
|
| 3571 |
+JSON Parameters: |
|
| 3572 |
+ |
|
| 3573 |
+- **Annotations** – Optional medata to associate with the service. |
|
| 3574 |
+ - **Name** – User-defined name for the service. |
|
| 3575 |
+ - **Labels** – A map of labels to associate with the service (e.g., |
|
| 3576 |
+ `{"key":"value"[,"key2":"value2"]}`).
|
|
| 3577 |
+- **Role** - Role of the node (worker/manager). |
|
| 3578 |
+- **Availability** - Availability of the node (active/pause/drain). |
|
| 3579 |
+ |
|
| 3580 |
+ |
|
| 3581 |
+**Status codes**: |
|
| 3582 |
+ |
|
| 3583 |
+- **200** – no error |
|
| 3584 |
+- **404** – no such node |
|
| 3585 |
+- **500** – server error |
|
| 3586 |
+ |
|
| 3504 | 3587 |
## 3.7 Swarm |
| 3505 | 3588 |
|
| 3506 | 3589 |
### Initialize a new swarm |
| ... | ... |
@@ -3353,8 +3353,8 @@ List nodes |
| 3353 | 3353 |
"UpdatedAt": "2016-06-07T20:31:11.999868824Z", |
| 3354 | 3354 |
"Spec": {
|
| 3355 | 3355 |
"Name": "my-node", |
| 3356 |
- "Role": "MANAGER", |
|
| 3357 |
- "Availability": "ACTIVE" |
|
| 3356 |
+ "Role": "manager", |
|
| 3357 |
+ "Availability": "active" |
|
| 3358 | 3358 |
"Labels": {
|
| 3359 | 3359 |
"foo": "bar" |
| 3360 | 3360 |
} |
| ... | ... |
@@ -3444,8 +3444,8 @@ Return low-level information on the node `id` |
| 3444 | 3444 |
"UpdatedAt": "2016-06-07T20:31:11.999868824Z", |
| 3445 | 3445 |
"Spec": {
|
| 3446 | 3446 |
"Name": "my-node", |
| 3447 |
- "Role": "MANAGER", |
|
| 3448 |
- "Availability": "ACTIVE" |
|
| 3447 |
+ "Role": "manager", |
|
| 3448 |
+ "Availability": "active" |
|
| 3449 | 3449 |
"Labels": {
|
| 3450 | 3450 |
"foo": "bar" |
| 3451 | 3451 |
} |
| ... | ... |
@@ -3501,6 +3501,84 @@ Return low-level information on the node `id` |
| 3501 | 3501 |
- **404** – no such node |
| 3502 | 3502 |
- **500** – server error |
| 3503 | 3503 |
|
| 3504 |
+### Remove a node |
|
| 3505 |
+ |
|
| 3506 |
+ |
|
| 3507 |
+`DELETE /nodes/<id>` |
|
| 3508 |
+ |
|
| 3509 |
+Remove a node [`id`] from the Swarm. |
|
| 3510 |
+ |
|
| 3511 |
+**Example request**: |
|
| 3512 |
+ |
|
| 3513 |
+ DELETE /nodes/24ifsmvkjbyhk HTTP/1.1 |
|
| 3514 |
+ |
|
| 3515 |
+**Example response**: |
|
| 3516 |
+ |
|
| 3517 |
+ HTTP/1.1 200 OK |
|
| 3518 |
+ Content-Length: 0 |
|
| 3519 |
+ Content-Type: text/plain; charset=utf-8 |
|
| 3520 |
+ |
|
| 3521 |
+**Status codes**: |
|
| 3522 |
+ |
|
| 3523 |
+- **200** – no error |
|
| 3524 |
+- **404** – no such node |
|
| 3525 |
+- **500** – server error |
|
| 3526 |
+ |
|
| 3527 |
+### Update a node |
|
| 3528 |
+ |
|
| 3529 |
+ |
|
| 3530 |
+`POST /nodes/<id>/update` |
|
| 3531 |
+ |
|
| 3532 |
+Update the node `id`. |
|
| 3533 |
+ |
|
| 3534 |
+The payload of the `POST` request is the new `NodeSpec` and |
|
| 3535 |
+overrides the current `NodeSpec` for the specified node. |
|
| 3536 |
+ |
|
| 3537 |
+If `Availability` or `Role` are omitted, this returns an |
|
| 3538 |
+error. Any other field omitted resets the current value to either |
|
| 3539 |
+an empty value or the default cluster-wide value. |
|
| 3540 |
+ |
|
| 3541 |
+**Example Request** |
|
| 3542 |
+ |
|
| 3543 |
+ POST /nodes/24ifsmvkjbyhk/update?version=8 HTTP/1.1 |
|
| 3544 |
+ Content-Type: application/json |
|
| 3545 |
+ |
|
| 3546 |
+ {
|
|
| 3547 |
+ "Availability": "active", |
|
| 3548 |
+ "Name": "node-name", |
|
| 3549 |
+ "Role": "manager", |
|
| 3550 |
+ "Labels": {
|
|
| 3551 |
+ "foo": "bar" |
|
| 3552 |
+ } |
|
| 3553 |
+ } |
|
| 3554 |
+ |
|
| 3555 |
+**Example response**: |
|
| 3556 |
+ |
|
| 3557 |
+ HTTP/1.1 200 OK |
|
| 3558 |
+ Content-Length: 0 |
|
| 3559 |
+ Content-Type: text/plain; charset=utf-8 |
|
| 3560 |
+ |
|
| 3561 |
+**Query parameters**: |
|
| 3562 |
+ |
|
| 3563 |
+- **version** – The version number of the node object being updated. This is |
|
| 3564 |
+ required to avoid conflicting writes. |
|
| 3565 |
+ |
|
| 3566 |
+JSON Parameters: |
|
| 3567 |
+ |
|
| 3568 |
+- **Annotations** – Optional medata to associate with the service. |
|
| 3569 |
+ - **Name** – User-defined name for the service. |
|
| 3570 |
+ - **Labels** – A map of labels to associate with the service (e.g., |
|
| 3571 |
+ `{"key":"value"[,"key2":"value2"]}`).
|
|
| 3572 |
+- **Role** - Role of the node (worker/manager). |
|
| 3573 |
+- **Availability** - Availability of the node (active/pause/drain). |
|
| 3574 |
+ |
|
| 3575 |
+ |
|
| 3576 |
+**Status codes**: |
|
| 3577 |
+ |
|
| 3578 |
+- **200** – no error |
|
| 3579 |
+- **404** – no such node |
|
| 3580 |
+- **500** – server error |
|
| 3581 |
+ |
|
| 3504 | 3582 |
## 3.7 Swarm |
| 3505 | 3583 |
|
| 3506 | 3584 |
### Initialize a new swarm |