Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Formally spec an API for interacting with integration managers #296

Open
turt2live opened this issue Jun 8, 2018 · 7 comments
Open

Formally spec an API for interacting with integration managers #296

turt2live opened this issue Jun 8, 2018 · 7 comments
Assignees
Labels
A-integrations Integration (Manager) API feature Suggestion for a significant extension which needs considerable consideration

Comments

@turt2live
Copy link
Member

turt2live commented Jun 8, 2018

Background

Integration managers are applications that help clients bring integrations (bridges, bots, etc) to users. This may be for things like setting up bridging to an IRC channel, adding Giphy to your room, or sharing a document with a widget. Integration managers were popularized by Riot, however other clients are starting to bring in support for the concept as well.

There are 2 integration managers at the time of writing this, each with different goals and APIs. Scalar (aka Modular) is the proprietary manager that ships with Riot and is developed specifically for Riot. Dimension (a project of mine) is open source and caters towards self-hosted integrations. As mentioned, both of these managers have different APIs once getting past the (very) basic client interaction. A formal spec should be documented so that future managers, and the existing ones, can adhere to a common standard for clients to use.

Components to consider for the spec

Although clients are encouraged to just nest an iframe (or similar) in their application, it can be difficult or undesirable to do so. A client with an objective for rich integration support may not want to use an iframe and instead opt to interact with the manager directly, providing their own UI/UX. Fractal, for example, is currently doing this with stickers: they have their own sticker picker which reaches out to the API directly instead of using an iframe.

The components available today are:

Some additional things that should be documented in my opinion are:

  • The API the manager uses to power its UI. Scalar's is informally documented here: https://github.com/turt2live/matrix-dimension/blob/master/docs/reference/scalar_server_api.md while Dimension's isn't formally documented (however, it does differ). The motivation for having a common spec for this is for those clients which do not want to (or can't) embed an iframe and instead want their own UI.
  • Inter-manager APIs. These currently don't exist, and it'd be nice if there was a way for managers to 'share' integrations. For example, using Giphy as supplied by Scalar and using a self-hosted IRC bridge. Full disclosure: this is on the roadmap for Dimension.
@turt2live
Copy link
Member Author

ftr this is on my personal todo list, although I wouldn't object if someone beat me to it (hence documenting it publicly).

@turt2live turt2live added the feature Suggestion for a significant extension which needs considerable consideration label Jul 19, 2018
@turt2live
Copy link
Member Author

turt2live commented Jul 31, 2018

At some point while discussing matrix-org/matrix-react-sdk#2062 the idea of a generic "make me a widget" API came up. This API should be well-standardized and be used by clients like Riot to create widgets.

The API would take in a widget type, and possibly a room ID with user information, and produce a JSON object that the client can send as a state event. The use case for this is so Riot, and other clients, can create Jitsi widgets, however the API can easily be expanded upon later.

This kind of API is important because matrix-org/matrix-spec-proposals#1089 only specifies what the data attributes for a widget are, not the query string. Although we could spec the query string, that would break existing widgets in the wild. Instead, the create widget API can produce a reliable URL for the client to use.

Edit: conversation context: https://matrix.to/#/!DdJkzRliezrwpNebLk:matrix.org/$153210051726DcSwY:t2l.io

@ara4n
Copy link
Member

ara4n commented Dec 17, 2018

ftr, we absolutely need this - the only reason this ticket hasn't been progressed by the core team (including @turt2live :) is lack of tuits.

@jittygitty
Copy link

jittygitty commented May 15, 2022

Why all of this?? What if we do not want any "INTERACTING"? Matrix.org can simply refuse connections from those with different integrations manager if they choose. Some of us simply want to easily use our OWN integrations manager, since although it appears your hardcoded scalar.vector.im one is proprietary and "closed-source", there are some "open-source"?

Can't you allow different integrations manager "immediately", letting us change the URL, if we don't connect with matrix.org?

element-hq/element-web#4913
element-hq/element-integration-manager#86
element-hq/element-web#6430
matrix-org/synapse#7702

@turt2live
Copy link
Member Author

You can specify an alternative integrations manager - please see the documentation for your client of choice.

This issue is about adding it formally to the specification to make it easier to write and maintain integration managers, however work on this is slow because integrations are second priority to first-party features which sustain Matrix.

Please do not spam your comments either. I've locked the issues which are considered resolved - please use the support rooms for your client of choice rather than posting a comment half a dozen times.

@richvdh
Copy link
Member

richvdh commented May 2, 2023

For links: see matrix-org/matrix-spec-proposals#1956 which I believe is a work-in-progress on this.

However: Element is replacing the current "integration manager API" with a "widget API" (see element-hq/element-meta#792). So maybe we should replace this issue with one about properly speccing the widget API (ie, landing matrix-org/matrix-spec-proposals#2764 etc)?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
A-integrations Integration (Manager) API feature Suggestion for a significant extension which needs considerable consideration
Projects
None yet
Development

No branches or pull requests

4 participants