prosody-modules: mod_rest/README.markdown@cfa00eea896f (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	Note that there is currently no authentication, so be careful with
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	16	exposing the API endpoint to the Internet.
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	17
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	18	## Enabling
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	19
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	20	``` {.lua}
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	21	Component "rest.example.net" "rest"
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	22	```
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	## Sending stanzas
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	25
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	26	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	27	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	28
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	29	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	30
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	31	``` {.sh}
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	32	curl https://prosody.example:5281/rest \
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	33	-H 'Content-Type: application/xmpp+xml' \
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	34	--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	35	<body>Hello!</body>
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	36	</body>'
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	37	```
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	38
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	39	The `Content-Type` MUST be `application/xmpp+xml`.
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	40
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	41	### Replies
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	42
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	43	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	44	long-polling style.
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	45
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	46	``` {.sh}
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	47	curl https://prosody.example:5281/rest \
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	48	-H 'Content-Type: application/xmpp+xml' \
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	49	--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	50	<ping xmlns="urn:xmpp:ping"/>
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	51	</iq>'
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	52	```
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	53
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	54	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	55	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	56	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	57	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	58
3799 f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3798 diff changeset	59	## Receiving stanzas
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3798 diff changeset	60
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3798 diff changeset	61	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	62
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3798 diff changeset	63	``` {.lua}
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3798 diff changeset	64	Component "rest.example.net" "rest"
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3798 diff changeset	65	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	66	```
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3798 diff changeset	67
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3798 diff changeset	68	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	69
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3798 diff changeset	70	``` {.xml}
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3798 diff changeset	71	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	72	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	73	Content-Length: 52
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	<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	76	<body>Hello</body>
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3798 diff changeset	77	</message>
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3798 diff changeset	78	```
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3798 diff changeset	79
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3798 diff changeset	80	### Replying
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	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	83	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	84
3801 ed5d7586a61e mod_rest: Map various HTTP status codes to XMPP stanza errors Kim Alvefur <zash@zash.se> parents: 3800 diff changeset	85	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	86	appropriate stanza error.
ed5d7586a61e mod_rest: Map various HTTP status codes to XMPP stanza errors Kim Alvefur <zash@zash.se> parents: 3800 diff changeset	87
3799 f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3798 diff changeset	88	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	89	`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	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	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	93	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	94
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3798 diff changeset	95	<message type="chat">
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3798 diff changeset	96	<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	97	</message>
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3798 diff changeset	98	```
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3798 diff changeset	99
3804 cfa00eea896f mod_rest: Add some text about the payload format Kim Alvefur <zash@zash.se> parents: 3801 diff changeset	100	## Payload format
cfa00eea896f mod_rest: Add some text about the payload format Kim Alvefur <zash@zash.se> parents: 3801 diff changeset	101
cfa00eea896f mod_rest: Add some text about the payload format Kim Alvefur <zash@zash.se> parents: 3801 diff changeset	102	``` {.xml}
cfa00eea896f mod_rest: Add some text about the payload format Kim Alvefur <zash@zash.se> parents: 3801 diff changeset	103	<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	104	...
cfa00eea896f mod_rest: Add some text about the payload format Kim Alvefur <zash@zash.se> parents: 3801 diff changeset	105	</message>
cfa00eea896f mod_rest: Add some text about the payload format Kim Alvefur <zash@zash.se> parents: 3801 diff changeset	106	```
cfa00eea896f mod_rest: Add some text about the payload format Kim Alvefur <zash@zash.se> parents: 3801 diff changeset	107
cfa00eea896f mod_rest: Add some text about the payload format Kim Alvefur <zash@zash.se> parents: 3801 diff changeset	108	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	109
cfa00eea896f mod_rest: Add some text about the payload format Kim Alvefur <zash@zash.se> parents: 3801 diff changeset	110	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	111
3798 4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	112	# Compatibility
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	113
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	114	Requires Prosody trunk / 0.12

author	Kim Alvefur <zash@zash.se>
	Mon, 30 Dec 2019 07:21:46 +0100
changeset 3804	cfa00eea896f
parent 3801	ed5d7586a61e
child 3805	d59fb4dcf100
permissions	-rw-r--r--