Software `/` code `/` prosody-modules

---
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>'
```

## 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
author	Kim Alvefur <zash@zash.se>
date	Mon, 30 Dec 2019 04:07:25 +0100
parent	3794:4b258329e6e4
child	3796:d1ad10b76b00