prosody-modules
117a979ef930
mod_rest/README.markdown

Find changesets by keywords by author, files, the commit message, revision number or hash, or revset expression.

Software / code / 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
parent 3857:8752e5b5dd08
child 3946: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