matrix-dimension/docs/dimension_api.md

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": []
    }
}