Mercurial > prosody-modules

comparison 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
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