Mercurial > prosody-modules

diff mod_rest/README.markdown @ 3794:4b258329e6e4
mod_rest: Initial commit of another RESTful API module
author: Kim Alvefur <zash@zash.se>
date: Mon, 30 Dec 2019 04:04:34 +0100
children: f51308fcba83
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/mod_rest/README.markdown	Mon Dec 30 04:04:34 2019 +0100
@@ -0,0 +1,54 @@
+---
+labels:
+- 'Stage-Alpha'
+summary: RESTful XMPP API
+---
+
+# Introduction
+
+This is yet another RESTful API for sending stanzas via Prosody.
+
+# Usage
+
+Note that there is currently **no authentication**, so be careful with
+exposing the API endpoint to the Internet.
+
+## Enabling
+
+``` {.lua}
+Component "rest.example.net" "rest"
+```
+
+## Sending stanzas
+
+The API endpoint becomes available at the path `/rest`, so the full URL
+will be something like `https://your-prosody.example:5281/rest`.
+
+To try it, simply `curl` an XML stanza payload:
+
+``` {.sh}
+curl https://prosody.example:5281/rest \
+    -H 'Content-Type: application/xmpp+xml' \
+    --data-binary '<message type="chat" to="user@example.org">
+            <body>Hello!</body>
+        </body>'
+```
+
+The `Content-Type` **MUST** be `application/xmpp+xml`.
+
+### Replies
+
+A POST containing an `<iq>` stanza automatically wait for the reply,
+long-polling style.
+
+``` {.sh}
+curl https://prosody.example:5281/rest \
+    -H 'Content-Type: application/xmpp+xml' \
+    --data-binary '<iq type="get" to="example.net">
+            <ping xmlns="urn:xmpp:ping"/>
+        </iq>'
+```
+
+# Compatibility
+
+Requires Prosody trunk / 0.12