Package io.github.ma1uta.matrix.application.api

Interface ProtocolApi

@Path("/_matrix/app/v1/thirdparty")
@Consumes("application/json")
@Produces("application/json")
public interface ProtocolApi

Application services may declare which protocols they support via their registration configuration for the homeserver. These networks are generally for third party services such as IRC that the application service is managing. Application services may populate a Matrix room directory for their registered protocols, as defined in the Client-Server API Extensions.
Each protocol may have several "locations" (also known as "third party locations" or "3PLs"). A location within a protocol is a place in the third party network, such as an IRC channel. Users of the third party network may also be represented by the application service.
Locations and users can be searched by fields defined by the application service, such as by display name or other attribute. When clients request the homeserver to search in a particular "network" (protocol), the search fields will be passed along to the application service for filtering.

Method Summary

Modifier and Type	Method	Description
void	location(String alias, javax.ws.rs.core.UriInfo uriInfo, javax.ws.rs.core.HttpHeaders httpHeaders, javax.ws.rs.container.AsyncResponse asyncResponse)	Retrieve an array of third party network locations from a Matrix room alias.
void	locationProtocol(String protocol, javax.ws.rs.core.UriInfo uriInfo, javax.ws.rs.core.HttpHeaders httpHeaders, javax.ws.rs.container.AsyncResponse asyncResponse)	Retrieve a list of Matrix portal rooms that lead to the matched third party location.
void	protocol(String protocol, javax.ws.rs.core.UriInfo uriInfo, javax.ws.rs.core.HttpHeaders httpHeaders, javax.ws.rs.container.AsyncResponse asyncResponse)	This API is called by the homeserver when it wants to present clients with specific information about the various third party networks that an application service supports.
void	user(String userId, javax.ws.rs.core.UriInfo uriInfo, javax.ws.rs.core.HttpHeaders httpHeaders, javax.ws.rs.container.AsyncResponse asyncResponse)	Retrieve an array of third party users from a Matrix User ID.
void	userProtocol(String protocol, javax.ws.rs.core.UriInfo uriInfo, javax.ws.rs.core.HttpHeaders httpHeaders, javax.ws.rs.container.AsyncResponse asyncResponse)	This API is called by the homeserver in order to retrieve a Matrix User ID linked to a user on the third party network, given a set of user parameters.

Method Detail

protocol

@GET
@Path("/protocol/{protocol}")
void protocol(@PathParam("protocol")
              String protocol,
              @Context
              javax.ws.rs.core.UriInfo uriInfo,
              @Context
              javax.ws.rs.core.HttpHeaders httpHeaders,
              @Suspended
              javax.ws.rs.container.AsyncResponse asyncResponse)

This API is called by the homeserver when it wants to present clients with specific information about the various third party networks that an application service supports.
Requires Auth: Yes.
Return: Protocol.

Status code 200: The protocol was found and metadata returned.

Status code 401: The homeserver has not supplied credentials to the application service. Optional error information can be included in the body of this response.

Status code 403: The credentials supplied by the homeserver were rejected.

Status code 404: No protocol was found with the given path.The protocol is unknown.

Parameters:

protocol - Required. The name of the protocol.

uriInfo - Information about the request.

httpHeaders - Http headers.

asyncResponse - Asynchronous response.

locationProtocol

@GET
@Path("/location/{protocol}")
void locationProtocol(@PathParam("protocol")
                      String protocol,
                      @Context
                      javax.ws.rs.core.UriInfo uriInfo,
                      @Context
                      javax.ws.rs.core.HttpHeaders httpHeaders,
                      @Suspended
                      javax.ws.rs.container.AsyncResponse asyncResponse)

Retrieve a list of Matrix portal rooms that lead to the matched third party location.
Requires Auth: Yes.
Return: List of the ProtocolLocations.

Status code 200: At least one portal room was found.

Status code 401: The homeserver has not supplied credentials to the application service. Optional error information can be included in the body of this response.

Status code 403: The credentials supplied by the homeserver were rejected.

Status code 404: No mappings were found with the given parameters.

Parameters:

protocol - Required. The protocol ID.

uriInfo - Information about the request.

httpHeaders - Http headers.

asyncResponse - Asynchronous response.

userProtocol

@GET
@Path("/user/{protocol}")
void userProtocol(@PathParam("protocol")
                  String protocol,
                  @Context
                  javax.ws.rs.core.UriInfo uriInfo,
                  @Context
                  javax.ws.rs.core.HttpHeaders httpHeaders,
                  @Suspended
                  javax.ws.rs.container.AsyncResponse asyncResponse)

This API is called by the homeserver in order to retrieve a Matrix User ID linked to a user on the third party network, given a set of user parameters. Required Auth: Yes.
Return: List of the ProtocolUsers.

Status code 200: The Matrix User IDs found with the given parameters.

Status code 401: The homeserver has not supplied credentials to the application service. Optional error information can be included in the body of this response.

Status code 403: The credentials supplied by the homeserver were rejected.

Status code 404: No users were found with the given parameters.

Parameters:

protocol - Required. The protocol ID.

uriInfo - Information about the request.

httpHeaders - Http headers.

asyncResponse - Asynchronous response.

location

@GET
@Path("/location")
void location(@QueryParam("alias")
              String alias,
              @Context
              javax.ws.rs.core.UriInfo uriInfo,
              @Context
              javax.ws.rs.core.HttpHeaders httpHeaders,
              @Suspended
              javax.ws.rs.container.AsyncResponse asyncResponse)

Retrieve an array of third party network locations from a Matrix room alias.
Requires Auth: Yes.
Return: List of the ProtocolLocations.

Status code 200: All found third party locations.

Status code 401: The homeserver has not supplied credentials to the application service. Optional error information can be included in the body of this response.

Status code 403: The credentials supplied by the homeserver were rejected.

Status code 404: No mappings were found with the given parameters.

Parameters:

alias - Required. The Matrix room alias to look up.

uriInfo - Information about the request.

httpHeaders - Http headers.

asyncResponse - Asynchronous response.

user

@GET
@Path("/user")
void user(@QueryParam("userid")
          String userId,
          @Context
          javax.ws.rs.core.UriInfo uriInfo,
          @Context
          javax.ws.rs.core.HttpHeaders httpHeaders,
          @Suspended
          javax.ws.rs.container.AsyncResponse asyncResponse)

Retrieve an array of third party users from a Matrix User ID.
Requires Auth: Yes.
Return: List of the ProtocolUsers.

Status code 200: An array of third party users.

Status code 401: The homeserver has not supplied credentials to the application service. Optional error information can be included in the body of this response.

Status code 403: The credentials supplied by the homeserver were rejected.

Status code 404: No mappings were found with the given parameters.

Parameters:

userId - Required. The Matrix User ID to look up.

uriInfo - Information about the request.

httpHeaders - Http headers.

asyncResponse - Asynchronous response.