Mercurial > prosody-modules

diff mod_rest/README.markdown @ 3813:aa1ad69c7c10

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
mod_rest: Add JSON support
author Kim Alvefur <zash@zash.se>
date Wed, 01 Jan 2020 16:21:28 +0100
parents a70f5a6c7f01
children d3757e089433
line wrap: on
line diff
--- a/mod_rest/README.markdown	Wed Jan 01 16:19:10 2020 +0100
+++ b/mod_rest/README.markdown	Wed Jan 01 16:21:28 2020 +0100
@@ -35,7 +35,21 @@
         </body>'
 ```
 
-The `Content-Type` **MUST** be `application/xmpp+xml`.
+or a JSON payload:
+
+``` {.sh}
+curl https://prosody.example:5281/rest \
+    --oauth2-bearer dmVyeSBzZWNyZXQgdG9rZW4K \
+    -H 'Content-Type: application/json' \
+    --data-binary '{
+           "body" : "Hello!",
+           "kind" : "message",
+           "to" : "user@example.org",
+           "type" : "chat"
+        }'
+```
+
+The `Content-Type` header is important!
 
 ### Replies
 
@@ -66,18 +80,40 @@
 rest_callback_url = "http://my-api.example:9999/stanzas"
 ```
 
+To enable JSON payloads set
+
+``` {.lua}
+rest_callback_content_type = "application/json"
+```
+
 Example callback looks like:
 
 ``` {.xml}
 POST /stanzas HTTP/1.1
 Content-Type: application/xmpp+xml
-Content-Length: 52
+Content-Length: 102
 
 <message to="bot@rest.example.net" from="user@example.com" type="chat">
 <body>Hello</body>
 </message>
 ```
 
+or as JSON:
+
+``` {.json}
+POST /stanzas HTTP/1.1
+Content-Type: application/json
+Content-Length: 133
+
+{
+   "body" : "Hello",
+   "from" : "user@example.com",
+   "kind" : "message",
+   "to" : "bot@rest.example.net",
+   "type" : "chat"
+}
+```
+
 ### Replying
 
 To accept the stanza without returning a reply, respond with HTTP status
@@ -100,6 +136,20 @@
 
 ## Payload format
 
+### JSON
+
+``` {.json}
+{
+   "body" : "Hello!",
+   "kind" : "message",
+   "type" : "chat"
+}
+```
+
+Mapping of various XMPP stanza payloads to JSON.
+
+### XML
+
 ``` {.xml}
 <message type="" id="" to="" from="" xml:lang="">
 ...
@@ -119,7 +169,7 @@
 
 Simple echo bot that responds to messages:
 
-```python
+``` {.python}
 from flask import Flask, Response, request
 import xml.etree.ElementTree as ET