Mercurial > prosody-modules
comparison mod_rest/README.markdown @ 3890:117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
| author | Kim Alvefur <zash@zash.se> |
|---|---|
| date | Sat, 08 Feb 2020 15:29:35 +0100 |
| parents | 8752e5b5dd08 |
| children | 2a5b42e4db07 |
comparison
equal
deleted
inserted
replaced
| 3889:59765d1bb6dc | 3890:117a979ef930 |
|---|---|
| 373 `items` | 373 `items` |
| 374 : Boolean `true` in a `kind:iq` `type:get` for a service discovery | 374 : Boolean `true` in a `kind:iq` `type:get` for a service discovery |
| 375 items list query. The response contain an array of items like | 375 items list query. The response contain an array of items like |
| 376 `{"jid":"xmpp.address.here","name":"Description of item"}`. | 376 `{"jid":"xmpp.address.here","name":"Description of item"}`. |
| 377 | 377 |
| 378 #### Ad-Hoc Commands | |
| 379 | |
| 380 Used to execute arbitrary commands on supporting entities. | |
| 381 | |
| 382 `command` | |
| 383 | |
| 384 : String representing the command `node` or Map with the following | |
| 385 possible fields: | |
| 386 | |
| 387 `node` | |
| 388 : Required string with node from disco\#items query for the | |
| 389 command to execute. | |
| 390 | |
| 391 `action` | |
| 392 : Optional enum string defaulting to `"execute"`. Multi-step | |
| 393 commands may involve `"next"`, `"prev"`, `"complete"` or | |
| 394 `"cancel"`. | |
| 395 | |
| 396 `actions` | |
| 397 : Set (map of strings to `true`) with available actions to proceed | |
| 398 with in multi-step commands. | |
| 399 | |
| 400 `status` | |
| 401 : String describing the status of the command, normally | |
| 402 `"executing"`. | |
| 403 | |
| 404 `sessionid` | |
| 405 : Random session ID issued by the responder to identify the | |
| 406 session in multi-step commands. | |
| 407 | |
| 408 `note` | |
| 409 : Map with `"type"` and `"text"` fields that carry simple result | |
| 410 information. | |
| 411 | |
| 412 `form` | |
| 413 : Data form with description of expected input and data types in | |
| 414 the next step of multi-step commands. **TODO** document format. | |
| 415 | |
| 416 `data` | |
| 417 : Map with only the data for result dataforms. Fields may be | |
| 418 stings or arrays of strings. | |
| 419 | |
| 420 ##### Example | |
| 421 | |
| 422 Discovering commands: | |
| 423 | |
| 424 ``` {.json} | |
| 425 { | |
| 426 "disco" : { | |
| 427 "node" : "http://jabber.org/protocol/commands" | |
| 428 }, | |
| 429 "id" : "8iN9hwdAAcfTBchm", | |
| 430 "kind" : "iq", | |
| 431 "to" : "example.com", | |
| 432 "type" : "get" | |
| 433 } | |
| 434 ``` | |
| 435 | |
| 436 Response: | |
| 437 | |
| 438 ``` {.json} | |
| 439 { | |
| 440 "from" : "example.com", | |
| 441 "id" : "8iN9hwdAAcfTBchm", | |
| 442 "items" : [ | |
| 443 { | |
| 444 "jid" : "example.com", | |
| 445 "name" : "Get uptime", | |
| 446 "node" : "uptime" | |
| 447 } | |
| 448 ], | |
| 449 "kind" : "iq", | |
| 450 "type" : "result" | |
| 451 } | |
| 452 ``` | |
| 453 | |
| 454 Execute the command: | |
| 455 | |
| 456 ``` {.json} | |
| 457 { | |
| 458 "command" : { | |
| 459 "node" : "uptime" | |
| 460 }, | |
| 461 "id" : "Jv-87nRaP6Mnrp8l", | |
| 462 "kind" : "iq", | |
| 463 "to" : "example.com", | |
| 464 "type" : "set" | |
| 465 } | |
| 466 ``` | |
| 467 | |
| 468 Executed: | |
| 469 | |
| 470 ``` {.json} | |
| 471 { | |
| 472 "command" : { | |
| 473 "node" : "uptime", | |
| 474 "note" : { | |
| 475 "text" : "This server has been running for 0 days, 20 hours and 54 minutes (since Fri Feb 7 18:05:30 2020)", | |
| 476 "type" : "info" | |
| 477 }, | |
| 478 "sessionid" : "6380880a-93e9-4f13-8ee2-171927a40e67", | |
| 479 "status" : "completed" | |
| 480 }, | |
| 481 "from" : "example.com", | |
| 482 "id" : "Jv-87nRaP6Mnrp8l", | |
| 483 "kind" : "iq", | |
| 484 "type" : "result" | |
| 485 } | |
| 486 ``` | |
| 487 | |
| 488 - **TODO** Describe multi-step commands with dataforms. | |
| 489 | |
| 378 # Compatibility | 490 # Compatibility |
| 379 | 491 |
| 380 Requires Prosody trunk / 0.12 | 492 Requires Prosody trunk / 0.12 |