mod_rest: Catch one (1) reply to a POST-ed stanza from an internal source
This will primarily cover error replies, and only those generated by the
same Prosody instance using the `origin.reply()` method.
---
labels:
- 'Stage-Alpha'
summary: RESTful XMPP API
---
# Introduction
This is yet another RESTful API for sending and receiving stanzas via
Prosody. It can be used to build bots and components implemented as HTTP
services.
# Usage
Note that there is currently **no authentication**, so be careful with
exposing the API endpoint to the Internet.
## Enabling
``` {.lua}
Component "rest.example.net" "rest"
```
## Sending stanzas
The API endpoint becomes available at the path `/rest`, so the full URL
will be something like `https://your-prosody.example:5281/rest`.
To try it, simply `curl` an XML stanza payload:
``` {.sh}
curl https://prosody.example:5281/rest \
-H 'Content-Type: application/xmpp+xml' \
--data-binary '<message type="chat" to="user@example.org">
<body>Hello!</body>
</body>'
```
The `Content-Type` **MUST** be `application/xmpp+xml`.
### Replies
A POST containing an `<iq>` stanza automatically wait for the reply,
long-polling style.
``` {.sh}
curl https://prosody.example:5281/rest \
-H 'Content-Type: application/xmpp+xml' \
--data-binary '<iq type="get" to="example.net">
<ping xmlns="urn:xmpp:ping"/>
</iq>'
```
Replies to other kinds of stanzas that are generated by the same Prosody
instance *MAY* be returned in the HTTP response. Replies from other
entities (connected clients or remote servers) will not be returned, but
can be forwarded via the callback API described in the next section.
## Receiving stanzas
TL;DR: Set this webhook callback URL, get XML `POST`-ed there.
``` {.lua}
Component "rest.example.net" "rest"
rest_callback_url = "http://my-api.example:9999/stanzas"
```
Example callback looks like:
``` {.xml}
POST /stanzas HTTP/1.1
Content-Type: application/xmpp+xml
Content-Length: 52
<message to="bot@rest.example.net" from="user@example.com" type="chat">
<body>Hello</body>
</message>
```
### Replying
To accept the stanza without returning a reply, respond with HTTP status
code `202` or `204`.
For full control over the response, set the `Content-Type` header to
`application/xmpp+xml` and return an XMPP stanza as an XML snippet.
``` {.xml}
HTTP/1.1 200 Ok
Content-Type: application/xmpp+xml
<message type="chat">
<body>Yes, this is bot</body>
</message>
```
# Compatibility
Requires Prosody trunk / 0.12