Software /
code /
prosody-modules
Comparison
mod_rest/README.markdown @ 3813:aa1ad69c7c10
mod_rest: Add JSON support
author | Kim Alvefur <zash@zash.se> |
---|---|
date | Wed, 01 Jan 2020 16:21:28 +0100 |
parent | 3809:a70f5a6c7f01 |
child | 3820:d3757e089433 |
comparison
equal
deleted
inserted
replaced
3812:f027b8b1e794 | 3813:aa1ad69c7c10 |
---|---|
33 --data-binary '<message type="chat" to="user@example.org"> | 33 --data-binary '<message type="chat" to="user@example.org"> |
34 <body>Hello!</body> | 34 <body>Hello!</body> |
35 </body>' | 35 </body>' |
36 ``` | 36 ``` |
37 | 37 |
38 The `Content-Type` **MUST** be `application/xmpp+xml`. | 38 or a JSON payload: |
39 | |
40 ``` {.sh} | |
41 curl https://prosody.example:5281/rest \ | |
42 --oauth2-bearer dmVyeSBzZWNyZXQgdG9rZW4K \ | |
43 -H 'Content-Type: application/json' \ | |
44 --data-binary '{ | |
45 "body" : "Hello!", | |
46 "kind" : "message", | |
47 "to" : "user@example.org", | |
48 "type" : "chat" | |
49 }' | |
50 ``` | |
51 | |
52 The `Content-Type` header is important! | |
39 | 53 |
40 ### Replies | 54 ### Replies |
41 | 55 |
42 A POST containing an `<iq>` stanza automatically wait for the reply, | 56 A POST containing an `<iq>` stanza automatically wait for the reply, |
43 long-polling style. | 57 long-polling style. |
64 Component "rest.example.net" "rest" | 78 Component "rest.example.net" "rest" |
65 rest_credentials = "Bearer dmVyeSBzZWNyZXQgdG9rZW4K" | 79 rest_credentials = "Bearer dmVyeSBzZWNyZXQgdG9rZW4K" |
66 rest_callback_url = "http://my-api.example:9999/stanzas" | 80 rest_callback_url = "http://my-api.example:9999/stanzas" |
67 ``` | 81 ``` |
68 | 82 |
83 To enable JSON payloads set | |
84 | |
85 ``` {.lua} | |
86 rest_callback_content_type = "application/json" | |
87 ``` | |
88 | |
69 Example callback looks like: | 89 Example callback looks like: |
70 | 90 |
71 ``` {.xml} | 91 ``` {.xml} |
72 POST /stanzas HTTP/1.1 | 92 POST /stanzas HTTP/1.1 |
73 Content-Type: application/xmpp+xml | 93 Content-Type: application/xmpp+xml |
74 Content-Length: 52 | 94 Content-Length: 102 |
75 | 95 |
76 <message to="bot@rest.example.net" from="user@example.com" type="chat"> | 96 <message to="bot@rest.example.net" from="user@example.com" type="chat"> |
77 <body>Hello</body> | 97 <body>Hello</body> |
78 </message> | 98 </message> |
79 ``` | 99 ``` |
80 | 100 |
101 or as JSON: | |
102 | |
103 ``` {.json} | |
104 POST /stanzas HTTP/1.1 | |
105 Content-Type: application/json | |
106 Content-Length: 133 | |
107 | |
108 { | |
109 "body" : "Hello", | |
110 "from" : "user@example.com", | |
111 "kind" : "message", | |
112 "to" : "bot@rest.example.net", | |
113 "type" : "chat" | |
114 } | |
115 ``` | |
116 | |
81 ### Replying | 117 ### Replying |
82 | 118 |
83 To accept the stanza without returning a reply, respond with HTTP status | 119 To accept the stanza without returning a reply, respond with HTTP status |
84 code `202` or `204`. | 120 code `202` or `204`. |
85 | 121 |
97 <body>Yes, this is bot</body> | 133 <body>Yes, this is bot</body> |
98 </message> | 134 </message> |
99 ``` | 135 ``` |
100 | 136 |
101 ## Payload format | 137 ## Payload format |
138 | |
139 ### JSON | |
140 | |
141 ``` {.json} | |
142 { | |
143 "body" : "Hello!", | |
144 "kind" : "message", | |
145 "type" : "chat" | |
146 } | |
147 ``` | |
148 | |
149 Mapping of various XMPP stanza payloads to JSON. | |
150 | |
151 ### XML | |
102 | 152 |
103 ``` {.xml} | 153 ``` {.xml} |
104 <message type="" id="" to="" from="" xml:lang=""> | 154 <message type="" id="" to="" from="" xml:lang=""> |
105 ... | 155 ... |
106 </message> | 156 </message> |
117 | 167 |
118 ## Python / Flask | 168 ## Python / Flask |
119 | 169 |
120 Simple echo bot that responds to messages: | 170 Simple echo bot that responds to messages: |
121 | 171 |
122 ```python | 172 ``` {.python} |
123 from flask import Flask, Response, request | 173 from flask import Flask, Response, request |
124 import xml.etree.ElementTree as ET | 174 import xml.etree.ElementTree as ET |
125 | 175 |
126 app = Flask("echobot") | 176 app = Flask("echobot") |
127 | 177 |