prosody-modules: mod_rest/README.markdown@d3757e089433 (annotated)

3798 4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	1	---
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	2	labels:
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	3	- 'Stage-Alpha'
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	4	summary: RESTful XMPP API
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	5	---
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	6
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	7	# Introduction
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	8
3799 f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3798 diff changeset	9	This is yet another RESTful API for sending and receiving stanzas via
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3798 diff changeset	10	Prosody. It can be used to build bots and components implemented as HTTP
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3798 diff changeset	11	services.
3798 4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	12
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	13	# Usage
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	14
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	15	## Enabling
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	16
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	17	``` {.lua}
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	18	Component "rest.example.net" "rest"
3806 f88e07630e4e mod_rest: Add support for simple Bearer token auth Kim Alvefur <zash@zash.se> parents: 3805 diff changeset	19	rest_credentials = "Bearer dmVyeSBzZWNyZXQgdG9rZW4K"
3798 4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	20	```
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	21
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	22	## Sending stanzas
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	23
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	24	The API endpoint becomes available at the path `/rest`, so the full URL
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	25	will be something like `https://your-prosody.example:5281/rest`.
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	26
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	27	To try it, simply `curl` an XML stanza payload:
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	28
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	29	``` {.sh}
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	30	curl https://prosody.example:5281/rest \
3806 f88e07630e4e mod_rest: Add support for simple Bearer token auth Kim Alvefur <zash@zash.se> parents: 3805 diff changeset	31	--oauth2-bearer dmVyeSBzZWNyZXQgdG9rZW4K \
3798 4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	32	-H 'Content-Type: application/xmpp+xml' \
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	33	--data-binary '<message type="chat" to="user@example.org">
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	34	<body>Hello!</body>
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	35	</body>'
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	36	```
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	37
3817 aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	38	or a JSON payload:
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	39
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	40	``` {.sh}
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	41	curl https://prosody.example:5281/rest \
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	42	--oauth2-bearer dmVyeSBzZWNyZXQgdG9rZW4K \
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	43	-H 'Content-Type: application/json' \
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	44	--data-binary '{
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	45	"body" : "Hello!",
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	46	"kind" : "message",
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	47	"to" : "user@example.org",
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	48	"type" : "chat"
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	49	}'
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	50	```
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	51
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	52	The `Content-Type` header is important!
3798 4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	53
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	54	### Replies
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	55
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	56	A POST containing an `<iq>` stanza automatically wait for the reply,
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	57	long-polling style.
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	58
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	59	``` {.sh}
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	60	curl https://prosody.example:5281/rest \
3806 f88e07630e4e mod_rest: Add support for simple Bearer token auth Kim Alvefur <zash@zash.se> parents: 3805 diff changeset	61	--oauth2-bearer dmVyeSBzZWNyZXQgdG9rZW4K \
3798 4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	62	-H 'Content-Type: application/xmpp+xml' \
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	63	--data-binary '<iq type="get" to="example.net">
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	64	<ping xmlns="urn:xmpp:ping"/>
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	65	</iq>'
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	66	```
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	67
3800 d1ad10b76b00 mod_rest: Catch one (1) reply to a POST-ed stanza from an internal source Kim Alvefur <zash@zash.se> parents: 3799 diff changeset	68	Replies to other kinds of stanzas that are generated by the same Prosody
d1ad10b76b00 mod_rest: Catch one (1) reply to a POST-ed stanza from an internal source Kim Alvefur <zash@zash.se> parents: 3799 diff changeset	69	instance MAY be returned in the HTTP response. Replies from other
d1ad10b76b00 mod_rest: Catch one (1) reply to a POST-ed stanza from an internal source Kim Alvefur <zash@zash.se> parents: 3799 diff changeset	70	entities (connected clients or remote servers) will not be returned, but
d1ad10b76b00 mod_rest: Catch one (1) reply to a POST-ed stanza from an internal source Kim Alvefur <zash@zash.se> parents: 3799 diff changeset	71	can be forwarded via the callback API described in the next section.
d1ad10b76b00 mod_rest: Catch one (1) reply to a POST-ed stanza from an internal source Kim Alvefur <zash@zash.se> parents: 3799 diff changeset	72
3799 f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3798 diff changeset	73	## Receiving stanzas
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3798 diff changeset	74
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3798 diff changeset	75	TL;DR: Set this webhook callback URL, get XML `POST`-ed there.
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3798 diff changeset	76
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3798 diff changeset	77	``` {.lua}
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3798 diff changeset	78	Component "rest.example.net" "rest"
3806 f88e07630e4e mod_rest: Add support for simple Bearer token auth Kim Alvefur <zash@zash.se> parents: 3805 diff changeset	79	rest_credentials = "Bearer dmVyeSBzZWNyZXQgdG9rZW4K"
3799 f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3798 diff changeset	80	rest_callback_url = "http://my-api.example:9999/stanzas"
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3798 diff changeset	81	```
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3798 diff changeset	82
3817 aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	83	To enable JSON payloads set
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	84
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	85	``` {.lua}
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	86	rest_callback_content_type = "application/json"
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	87	```
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	88
3799 f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3798 diff changeset	89	Example callback looks like:
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3798 diff changeset	90
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3798 diff changeset	91	``` {.xml}
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3798 diff changeset	92	POST /stanzas HTTP/1.1
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3798 diff changeset	93	Content-Type: application/xmpp+xml
3817 aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	94	Content-Length: 102
3799 f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3798 diff changeset	95
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3798 diff changeset	96	<message to="bot@rest.example.net" from="user@example.com" type="chat">
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3798 diff changeset	97	<body>Hello</body>
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3798 diff changeset	98	</message>
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3798 diff changeset	99	```
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3798 diff changeset	100
3817 aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	101	or as JSON:
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	102
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	103	``` {.json}
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	104	POST /stanzas HTTP/1.1
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	105	Content-Type: application/json
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	106	Content-Length: 133
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	107
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	108	{
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	109	"body" : "Hello",
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	110	"from" : "user@example.com",
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	111	"kind" : "message",
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	112	"to" : "bot@rest.example.net",
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	113	"type" : "chat"
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	114	}
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	115	```
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	116
3799 f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3798 diff changeset	117	### Replying
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3798 diff changeset	118
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3798 diff changeset	119	To accept the stanza without returning a reply, respond with HTTP status
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3798 diff changeset	120	code `202` or `204`.
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3798 diff changeset	121
3801 ed5d7586a61e mod_rest: Map various HTTP status codes to XMPP stanza errors Kim Alvefur <zash@zash.se> parents: 3800 diff changeset	122	HTTP status codes in the `4xx` and `5xx` range are mapped to an
ed5d7586a61e mod_rest: Map various HTTP status codes to XMPP stanza errors Kim Alvefur <zash@zash.se> parents: 3800 diff changeset	123	appropriate stanza error.
ed5d7586a61e mod_rest: Map various HTTP status codes to XMPP stanza errors Kim Alvefur <zash@zash.se> parents: 3800 diff changeset	124
3799 f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3798 diff changeset	125	For full control over the response, set the `Content-Type` header to
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3798 diff changeset	126	`application/xmpp+xml` and return an XMPP stanza as an XML snippet.
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3798 diff changeset	127
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3798 diff changeset	128	``` {.xml}
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3798 diff changeset	129	HTTP/1.1 200 Ok
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3798 diff changeset	130	Content-Type: application/xmpp+xml
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3798 diff changeset	131
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3798 diff changeset	132	<message type="chat">
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3798 diff changeset	133	<body>Yes, this is bot</body>
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3798 diff changeset	134	</message>
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3798 diff changeset	135	```
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3798 diff changeset	136
3804 cfa00eea896f mod_rest: Add some text about the payload format Kim Alvefur <zash@zash.se> parents: 3801 diff changeset	137	## Payload format
cfa00eea896f mod_rest: Add some text about the payload format Kim Alvefur <zash@zash.se> parents: 3801 diff changeset	138
3817 aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	139	### JSON
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	140
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	141	``` {.json}
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	142	{
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	143	"body" : "Hello!",
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	144	"kind" : "message",
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	145	"type" : "chat"
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	146	}
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	147	```
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	148
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	149	Mapping of various XMPP stanza payloads to JSON.
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	150
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	151	### XML
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	152
3804 cfa00eea896f mod_rest: Add some text about the payload format Kim Alvefur <zash@zash.se> parents: 3801 diff changeset	153	``` {.xml}
cfa00eea896f mod_rest: Add some text about the payload format Kim Alvefur <zash@zash.se> parents: 3801 diff changeset	154	<message type="" id="" to="" from="" xml:lang="">
cfa00eea896f mod_rest: Add some text about the payload format Kim Alvefur <zash@zash.se> parents: 3801 diff changeset	155	...
cfa00eea896f mod_rest: Add some text about the payload format Kim Alvefur <zash@zash.se> parents: 3801 diff changeset	156	</message>
cfa00eea896f mod_rest: Add some text about the payload format Kim Alvefur <zash@zash.se> parents: 3801 diff changeset	157	```
cfa00eea896f mod_rest: Add some text about the payload format Kim Alvefur <zash@zash.se> parents: 3801 diff changeset	158
cfa00eea896f mod_rest: Add some text about the payload format Kim Alvefur <zash@zash.se> parents: 3801 diff changeset	159	An XML declaration (`<?xml?>`) MUST NOT be included.
cfa00eea896f mod_rest: Add some text about the payload format Kim Alvefur <zash@zash.se> parents: 3801 diff changeset	160
cfa00eea896f mod_rest: Add some text about the payload format Kim Alvefur <zash@zash.se> parents: 3801 diff changeset	161	The payload MUST contain one (1) `message`, `presence` or `iq` stanza.
cfa00eea896f mod_rest: Add some text about the payload format Kim Alvefur <zash@zash.se> parents: 3801 diff changeset	162
3805 d59fb4dcf100 mod_rest: Verify that @xmlns is left empty Kim Alvefur <zash@zash.se> parents: 3804 diff changeset	163	The stanzas MUST NOT have an `xmlns` attribute, and the default/empty
d59fb4dcf100 mod_rest: Verify that @xmlns is left empty Kim Alvefur <zash@zash.se> parents: 3804 diff changeset	164	namespace is treated as `jabber:client`.
d59fb4dcf100 mod_rest: Verify that @xmlns is left empty Kim Alvefur <zash@zash.se> parents: 3804 diff changeset	165
3812 02164f8aebac mod_rest: Add an example Flask thing Kim Alvefur <zash@zash.se> parents: 3806 diff changeset	166	# Examples
02164f8aebac mod_rest: Add an example Flask thing Kim Alvefur <zash@zash.se> parents: 3806 diff changeset	167
02164f8aebac mod_rest: Add an example Flask thing Kim Alvefur <zash@zash.se> parents: 3806 diff changeset	168	## Python / Flask
02164f8aebac mod_rest: Add an example Flask thing Kim Alvefur <zash@zash.se> parents: 3806 diff changeset	169
3824 d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3817 diff changeset	170	Simple echo bot that responds to messages as XML:
3812 02164f8aebac mod_rest: Add an example Flask thing Kim Alvefur <zash@zash.se> parents: 3806 diff changeset	171
3817 aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	172	``` {.python}
3812 02164f8aebac mod_rest: Add an example Flask thing Kim Alvefur <zash@zash.se> parents: 3806 diff changeset	173	from flask import Flask, Response, request
02164f8aebac mod_rest: Add an example Flask thing Kim Alvefur <zash@zash.se> parents: 3806 diff changeset	174	import xml.etree.ElementTree as ET
02164f8aebac mod_rest: Add an example Flask thing Kim Alvefur <zash@zash.se> parents: 3806 diff changeset	175
3813 a70f5a6c7f01 mod_rest: Apply Python source formatting on example Kim Alvefur <zash@zash.se> parents: 3812 diff changeset	176	app = Flask("echobot")
a70f5a6c7f01 mod_rest: Apply Python source formatting on example Kim Alvefur <zash@zash.se> parents: 3812 diff changeset	177
3812 02164f8aebac mod_rest: Add an example Flask thing Kim Alvefur <zash@zash.se> parents: 3806 diff changeset	178
02164f8aebac mod_rest: Add an example Flask thing Kim Alvefur <zash@zash.se> parents: 3806 diff changeset	179	@app.before_request
02164f8aebac mod_rest: Add an example Flask thing Kim Alvefur <zash@zash.se> parents: 3806 diff changeset	180	def parse():
02164f8aebac mod_rest: Add an example Flask thing Kim Alvefur <zash@zash.se> parents: 3806 diff changeset	181	request.stanza = ET.fromstring(request.data)
02164f8aebac mod_rest: Add an example Flask thing Kim Alvefur <zash@zash.se> parents: 3806 diff changeset	182
3813 a70f5a6c7f01 mod_rest: Apply Python source formatting on example Kim Alvefur <zash@zash.se> parents: 3812 diff changeset	183
a70f5a6c7f01 mod_rest: Apply Python source formatting on example Kim Alvefur <zash@zash.se> parents: 3812 diff changeset	184	@app.route("/", methods=["POST"])
3812 02164f8aebac mod_rest: Add an example Flask thing Kim Alvefur <zash@zash.se> parents: 3806 diff changeset	185	def hello():
3813 a70f5a6c7f01 mod_rest: Apply Python source formatting on example Kim Alvefur <zash@zash.se> parents: 3812 diff changeset	186	if request.stanza.tag == "message":
a70f5a6c7f01 mod_rest: Apply Python source formatting on example Kim Alvefur <zash@zash.se> parents: 3812 diff changeset	187	return Response(
a70f5a6c7f01 mod_rest: Apply Python source formatting on example Kim Alvefur <zash@zash.se> parents: 3812 diff changeset	188	"<message><body>Yes this is bot</body></message>",
a70f5a6c7f01 mod_rest: Apply Python source formatting on example Kim Alvefur <zash@zash.se> parents: 3812 diff changeset	189	content_type="application/xmpp+xml",
a70f5a6c7f01 mod_rest: Apply Python source formatting on example Kim Alvefur <zash@zash.se> parents: 3812 diff changeset	190	)
3812 02164f8aebac mod_rest: Add an example Flask thing Kim Alvefur <zash@zash.se> parents: 3806 diff changeset	191
3813 a70f5a6c7f01 mod_rest: Apply Python source formatting on example Kim Alvefur <zash@zash.se> parents: 3812 diff changeset	192	return Response(status=501)
3812 02164f8aebac mod_rest: Add an example Flask thing Kim Alvefur <zash@zash.se> parents: 3806 diff changeset	193
3813 a70f5a6c7f01 mod_rest: Apply Python source formatting on example Kim Alvefur <zash@zash.se> parents: 3812 diff changeset	194
a70f5a6c7f01 mod_rest: Apply Python source formatting on example Kim Alvefur <zash@zash.se> parents: 3812 diff changeset	195	if __name__ == "__main__":
3812 02164f8aebac mod_rest: Add an example Flask thing Kim Alvefur <zash@zash.se> parents: 3806 diff changeset	196	app.run()
02164f8aebac mod_rest: Add an example Flask thing Kim Alvefur <zash@zash.se> parents: 3806 diff changeset	197	```
02164f8aebac mod_rest: Add an example Flask thing Kim Alvefur <zash@zash.se> parents: 3806 diff changeset	198
3824 d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3817 diff changeset	199	And a JSON variant:
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3817 diff changeset	200
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3817 diff changeset	201	``` {.python}
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3817 diff changeset	202	from flask import Flask, Response, request, jsonify
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3817 diff changeset	203
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3817 diff changeset	204	app = Flask("echobot")
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3817 diff changeset	205
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3817 diff changeset	206
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3817 diff changeset	207	@app.route("/", methods=["POST"])
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3817 diff changeset	208	def hello():
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3817 diff changeset	209	print(request.data)
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3817 diff changeset	210	if request.is_json:
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3817 diff changeset	211	data = request.get_json()
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3817 diff changeset	212	if data["kind"] == "message":
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3817 diff changeset	213	return jsonify({"body": "hello"})
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3817 diff changeset	214
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3817 diff changeset	215	return Response(status=501)
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3817 diff changeset	216
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3817 diff changeset	217
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3817 diff changeset	218	if __name__ == "__main__":
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3817 diff changeset	219	app.run()
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3817 diff changeset	220	```
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3817 diff changeset	221
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3817 diff changeset	222	Remember to set `rest_callback_content_type = "application/json"` for
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3817 diff changeset	223	this to work.
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3817 diff changeset	224
3798 4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	225	# Compatibility
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	226
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	227	Requires Prosody trunk / 0.12

author	Kim Alvefur <zash@zash.se>
	Wed, 01 Jan 2020 18:11:55 +0100
changeset 3824	d3757e089433
parent 3817	aa1ad69c7c10
child 3830	21ffca4d3aae
permissions	-rw-r--r--