mirror of
https://github.com/turt2live/matrix-dimension.git
synced 2024-09-05 00:21:59 +00:00
174 lines
4.1 KiB
Markdown
174 lines
4.1 KiB
Markdown
# Dimension API
|
|
|
|
Dimension has its own API that allows for management of integrations in Riot/Matrix.
|
|
|
|
## Types of integrations
|
|
|
|
### Simple Bots
|
|
|
|
* Can only be in a room or not
|
|
* No state information held
|
|
|
|
### Complex Bots
|
|
|
|
* Simple Bots that hold state information
|
|
|
|
### Bridges
|
|
|
|
* Manage their own state through dedicated API endpoints
|
|
|
|
## Endpoints
|
|
|
|
### `GET /api/v1/dimension/integrations/{roomId}?scalar_token=your_token_here`
|
|
|
|
**Parameters**
|
|
* `{roomId}` - The room ID to get integrations for
|
|
* `scalar_token` - The scalar (dimension) token to authenticate with
|
|
|
|
**Example Response**
|
|
```
|
|
TODO
|
|
```
|
|
|
|
### `DELETE /api/v1/dimension/integrations/{roomId}/{type}/{integrationType}?scalar_token=your_token_here`
|
|
|
|
**Parameters**
|
|
* `{roomId}` - The room ID to remove the integration from
|
|
* `{type}` - The integration type (eg: `bot`, `complex-bot`, `bridge`, etc)
|
|
* `{integrationType}` - The integration subtype (eg: `irc`, `rssbot`, `giphy`, etc)
|
|
* `scalar_token` - The scalar (dimension) token to authenticate with
|
|
|
|
**Example Response**
|
|
```
|
|
TODO
|
|
```
|
|
|
|
### `PUT /api/v1/dimension/integrations/{roomId}/{type}/{integrationType}/state`
|
|
|
|
**Parameters**
|
|
* `{roomId}` - The room ID to update the integration state in
|
|
* `{type}` - The integration type (eg: `bot`, `complex-bot`, `bridge`, etc)
|
|
* `{integrationType}` - The integration subtype (eg: `irc`, `rssbot`, `giphy`, etc)
|
|
|
|
**Example Body**
|
|
```
|
|
{
|
|
"scalar_token": "your_token_here",
|
|
"state": {
|
|
// integration specific state goes here
|
|
}
|
|
}
|
|
```
|
|
|
|
### `GET /api/v1/dimension/integrations/{roomId}/{type}/{integrationType}/state?scalar_token=your_token_here`
|
|
|
|
**Parameters**
|
|
* `{roomId}` - The room ID to get the integration state in
|
|
* `{type}` - The integration type (eg: `bot`, `complex-bot`, `bridge`, etc)
|
|
* `{integrationType}` - The integration subtype (eg: `irc`, `rssbot`, `giphy`, etc)
|
|
* `scalar_token` - The scalar (dimension) token to authenticate with
|
|
|
|
**Response**
|
|
|
|
An object representing the integration-specific state. See the documentation for the desired integration for more information.
|
|
|
|
### `GET /api/v1/dimension/{type}/{integrationType}/oauth/url?redirect=your_url_here&scalar_token=your_token_here`
|
|
|
|
**Parameters**
|
|
* `{type}` - The integration type (eg: `bot`, `complex-bot`, `bridge`, etc)
|
|
* `{integrationType}` - The integration subtype (eg: `irc`, `rssbot`, `giphy`, etc)
|
|
* `redirect` - The URL to redirect to when complete
|
|
* `scalar_token` - The scalar (dimension) token to authenticate with
|
|
|
|
**Example Response**
|
|
```
|
|
{
|
|
"url": "https://github.com/somewhere?with=params"
|
|
}
|
|
```
|
|
|
|
### `DELETE /api/v1/dimension/{type}/{integrationType}/oauth?scalar_token=your_token_here`
|
|
|
|
**Parameters**
|
|
* `{type}` - The integration type (eg: `bot`, `complex-bot`, `bridge`, etc)
|
|
* `{integrationType}` - The integration subtype (eg: `irc`, `rssbot`, `giphy`, etc)
|
|
* `scalar_token` - The scalar (dimension) token to authenticate with
|
|
|
|
**Example Response**
|
|
```
|
|
{}
|
|
```
|
|
|
|
## Integration State Information
|
|
|
|
### Simple Bots
|
|
|
|
Do not hold state.
|
|
|
|
### Complex Bots
|
|
|
|
#### RSS Bot
|
|
```
|
|
{
|
|
// Mutable using state API
|
|
"feeds": [
|
|
"https://some.domain.com/feed.rss",
|
|
"https://some.domain.com/another_feed.rss"
|
|
],
|
|
|
|
// Read only. Controlled by other users.
|
|
"immutableFeeds": [
|
|
"https://some.domain.com/third_feed.rss",
|
|
"https://some.domain.com/fourth_feed.rss"
|
|
]
|
|
}
|
|
```
|
|
|
|
#### Github
|
|
```
|
|
{
|
|
// Mutable using state API
|
|
"repositories": {
|
|
"turt2live/matrix-dimension": ["push", "pull_request", "issues", "issue_comment", "pull_request_review_comment", "labels", "milestones", "assignments"],
|
|
"turt2live/matrix-voyager-bot": []
|
|
},
|
|
|
|
// Read only.
|
|
"authenticated": true
|
|
}
|
|
```
|
|
|
|
*Unauthenticated response*
|
|
```
|
|
{
|
|
// Read only.
|
|
"repositories": {},
|
|
|
|
// Read only.
|
|
"authenticated": false
|
|
}
|
|
```
|
|
|
|
### Bridges
|
|
|
|
#### IRC
|
|
```
|
|
{
|
|
// Read only
|
|
"availableNetworks": [
|
|
{"name": "Freenode", "id": "freenode"},
|
|
{"name": "EsperNet", "id": "espernet"},
|
|
{"name": "OFTC", "id": "oftc"}
|
|
],
|
|
|
|
// Read only. Use IRC API to mutate
|
|
"channels": {
|
|
"freenode": [
|
|
"#dimensiontesting",
|
|
"#dimensiontest"
|
|
],
|
|
"espernet": [],
|
|
"oftc": []
|
|
}
|
|
}
|
|
``` |