From 98a38862d3ebd4417c5e5611319314bb415d1921 Mon Sep 17 00:00:00 2001 From: Wim Date: Wed, 9 Jan 2019 23:08:02 +0100 Subject: [PATCH] Add API documentation and example --- Api.md | 164 ++++++++++++++++++++++++++++++++++++++++++++++++++++ Features.md | 2 +- Home.md | 5 +- 3 files changed, 169 insertions(+), 2 deletions(-) create mode 100644 Api.md diff --git a/Api.md b/Api.md new file mode 100644 index 0000000..306d963 --- /dev/null +++ b/Api.md @@ -0,0 +1,164 @@ + + +- [OpenAPI specification](#openapi-specification) +- [Example discord/gitter/api gateway](#example-discordgitterapi-gateway) + - [Configure matterbridge.toml](#configure-matterbridgetoml) + - [Get the messages from the buffer (GET /api/messages)](#get-the-messages-from-the-buffer-get-apimessages) + - [Stream messages (GET /api/stream)](#stream-messages-get-apistream) + - [Send message (POST /api/message)](#send-message-post-apimessage) +- [Security](#security) +- [Projects using the API](#projects-using-the-api) + + + +## OpenAPI specification + +Matterbridge API spec can be found on https://app.swaggerhub.com/apis-docs/matterbridge/matterbridge-api/0.1.0-oas3 + +## Example discord/gitter/api gateway + +This example creates a gateway containing 3 bridges: discord,gitter and api. +The API will listen on localhost port 4242. + +### Configure matterbridge.toml + +This is based on the example in https://github.com/42wim/matterbridge/wiki/How-to-create-your-config + +We first add the API account configuration to this example, this makes the API listen on localhost port 4242 with a buffer of 1000 messages and the nicks we receive will look like "{nick}". + +```toml +[api.myapi] +BindAddress="127.0.0.1:4242" +Buffer=1000 +RemoteNickFormat="{NICK}" +``` + +Next we add the API gateway configuration, this make sure that we receive the messages from the other bridges and we can sent them. + +```toml +[[gateway.inout]] +account="api.myapi" +channel="api" +``` + +The full example + +```toml +[discord.mydiscord] +Token="MTk4NjIyNDgzNDcdOTI1MjQ4.Cl2FMZ.ZnCjm1XVW7vRze4b7Cq4se7kKWs-abD" +Server="myserver" + +[gitter.mygitter] +Token="319fda1761c6875739a489b6772daf2ace4b95d0" + +[api.myapi] +BindAddress="127.0.0.1:4242" +Buffer=1000 +RemoteNickFormat="{NICK}" + +[[gateway]] +name="gateway1" +enable=true + +[[gateway.inout]] +account="discord.mydiscord" +channel="general" + +[[gateway.inout]] +account="gitter.mygitter" +channel="42wim/mygreatproject" + +[[gateway.inout]] +account="api.myapi" +channel="api" +``` + +### Get the messages from the buffer (GET /api/messages) + +If we now type a "test" message in our "general" channel on discord, we get the following result + +```bash +$ curl http://localhost:4242/api/messages +``` + + +```json +[ + { + "text": "test", + "channel": "general", + "username": "wim", + "userid": "227183123686215680", + "avatar": "https://cdn.discordapp.com/avatars/227183947686215680/bd0e6c7fe63274597a4684884891b79d.jpg", + "account": "discord.mydiscord", + "event": "", + "protocol": "", + "gateway": "gateway1", + "parent_id": "", + "timestamp": "2019-01-09T22:37:18.647108348+01:00", + "id": "", + "Extra": null + } +] +``` + +After we got this message (and we didn't type anything else), the buffer will be empty and doing a curl will now give an empty result + +```bash +$ curl http://localhost:4242/api/messages +``` + +```json +[] +``` + +### Stream messages (GET /api/stream) + +If we now type a "test" message in our "general" channel on discord, we get the following result + +```bash +$ curl http://localhost:4242/api/stream +``` + +```json +{"text":"","channel":"","username":"","userid":"","avatar":"","account":"","event":"api_connected","protocol":"","gateway":"","parent_id":"","timestamp":"2019-01-09T22:48:33.398737344+01:00","id":"","Extra":null} +{"text":"test","channel":"general","username":"wim","userid":"227183123686215680","avatar":"https://cdn.discordapp.com/avatars/227183947686215680/bd0e6c7fe63274597a4684884891b79d.jpg","account":"discord.mydiscord","event":"","protocol":"","gateway":"gateway1","parent_id":"","timestamp":"2019-01-09T22:48:42.506629373+01:00","id":"","Extra":null} +``` + +At connect you first get a `api_connected` event, then you'll get a http stream of json messages + +### Send message (POST /api/message) + +We now post a `test` message from `randomuser` to the gateway `gateway1` + +Every bridge on the gateway (gitter and discord) will now receive this message. + +```bash +curl -XPOST -H 'Content-Type: application/json' -d '{"text":"test","username":"randomuser","gateway":"gateway1"}' http://localhost:4242/api/message +``` + +```json +{"text":"test","channel":"api","username":"randomuser","userid":"","avatar":"","account":"api.local","event":"","protocol":"api","gateway":"gateway1","parent_id":"","timestamp":"2019-01-09T22:53:51.618575236+01:00","id":"","Extra":null} +``` + +## Security +You can also protect the API with a token by adding a `token` option to your api account configuration. + +```toml +[api.myapi] +BindAddress="127.0.0.1:4242" +Buffer=1000 +RemoteNickFormat="{NICK}" +Token="verys3cret" +``` +If you now want to sent a message with curl you'll have to add a `Authorization: Bearer ` header + +```bash +curl -H "Authorization: Bearer verys3cret" http://localhost:4242/api/stream +``` + +## Projects using the API + +* [MatterLink](https://github.com/elytra/MatterLink) (Matterbridge link for Minecraft Server chat) +* [pyCord](https://github.com/NikkyAI/pyCord) (crossplatform chatbot) +* [Mattereddit](https://github.com/bonehurtingjuice/mattereddit) (Reddit chat support) diff --git a/Features.md b/Features.md index c3ffc20..a7e7c5d 100644 --- a/Features.md +++ b/Features.md @@ -61,5 +61,5 @@ See webhook in advanced for specific bridge information TODO Private groups are supported for Mattermost and Slack # API -TODO +See [[Api]] diff --git a/Home.md b/Home.md index b2b3886..aa90914 100644 --- a/Home.md +++ b/Home.md @@ -3,6 +3,9 @@ Welcome to the matterbridge wiki! ### FAQ The [[FAQ]] +### API +See [[Api]] + ### Features [[Features]] @@ -11,4 +14,4 @@ Some simple steps to create your configuration: [[How-to-create-your-config]] ### Screenshots Screenshots matrix/gitter/slack/discord/mattermost/irc -![](https://i.snag.gy/kKs309.jpg) \ No newline at end of file +![](https://i.snag.gy/kKs309.jpg)