Building an API to fetch information about all connections in Ant Media Server

Ant Media Server has a comprehensive collection of REST APIs broadly divided into two categories – Broadcast REST Service & Management REST Service, that enable developers/admins to query & manage the server in a flexible manner. Sometimes however we might come across a custom requirement to while working on a system where the default APIs might not be sufficient.

In this article, we will take a look at a simple way of building a custom HTTP API through the Ant Media Server plugin system which will help us fetch some valuable information about the connections currently connected to our server application. Once we are done playing with the Ant Media Java API exploration & plugin development we will see how the plugin is built, deployed, and used on the server.

Getting Started

To get started with our plugin development, I recommend you take a look at the sample plugin provided by the Ant Media team in their GitHub repository.

The first step would be to clone this repository to your development machine using your fav GitHub client. We will be using this plugin and as a basis to make & demonstrate our own plugin.

Once cloned import the SamplePlugin project into your IDE. The project is maven based. So make sure to use an appropriate IDE for development. I personally use & recommend the latest Eclipse JEE for maven-based projects. For standalone build & package operations makes sure your system has maven binary installed/set up properly.

Working in the IDE

Once the project has been imported into eclipse, the IDE will begin resolving maven dependencies and installing them into the local maven cache. This process can take a little time depending on your network speed & system performance.

Once the resolution is complete (and if all went well), you will see no errrors in the problems panel.

Now we must open the relevant files of the SamplePlugin and update them as necessary.

Using SamplePlugin to create our own plugin

• Using eclipse right click the project -> refactor & rename the plugin to CustomApiPlugin.
• Edit the pom.xml file and make sure to change all occurrences of SamplePlugin to CustomApiPlugin.
• Edit pom.xml and change the finalname value – PluginApp to CustomApiPlugin
• From eclipse package explorer expand the package io.antmedia.plugin, right-click the plugin file SamplePlugin.java class file, and refactor-rename to CustomApiPlugin.java.
  
  

Writing new code

Now that the plugin structure is ready, we can now add our new functionality to it. The purpose of this plugin will be to expose an HTTP call that will return information (such as remote address etc) about the clients currently connected to the application.

Since this functionality will be exposed as an HTTP API call, we will be adding the logic to the file RestService.java located under the io.antmedia.rest package.

We will create a new package called com.rtmpworld.server.antmedia.plugin.sample.model under src that will hold our custom model/value object classes. Under this packager add a class called ConnectionInfo.java. for now we will add just two properties to it – sessionId & remoteAddress.

package com.rtmpworld.server.antmedia.plugin.sample.model;

public class ConnectionInfo {
	
	private String sessionId;
	
	private String remoteAddress;
	

	public String getSessionId() {
		return sessionId;
	}

	public void setSessionId(String sessionId) {
		this.sessionId = sessionId;
	}

	public String getRemoteAddress() {
		return remoteAddress;
	}

	public void setRemoteAddress(String remoteAddress) {
		this.remoteAddress = remoteAddress;
	}

}

Now open the file RestService.java in eclipse and add the following function to it towards the end.

@GET
@Path("/connections")
@Produces(MediaType.APPLICATION_JSON)
@Consumes(MediaType.APPLICATION_JSON)
public List<ConnectionInfo> getConnections() {
	CustomApiPlugin plugin = getPluginApp();
	
	List<ConnectionInfo> result = new ArrayList<ConnectionInfo>();
	Collection<Set<IConnection>> collections = plugin.getApplication().getConnections();		
	for (Iterator<Set<IConnection>> it = collections.iterator(); it.hasNext();) 
	{
		Set<IConnection> connections = it.next();
		for(IConnection connection : connections) {
			ConnectionInfo conn = new ConnectionInfo();
			conn.setSessionId(connection.getSessionId());
			conn.setRemoteAddress(connection.getRemoteAddress());
			result.add(conn);
		}
	}		
	return result;
}

NOTE: If you see any class import errors you must resolve them before moving forward.

About IConnection

IConnection is an interface to the various supported connection types on the ant media server. Excluding HLS (that I am not sure of), it should effectively provide information about RTMP, RTSP, and WebRTC connections on the server. I will encourage you to use the eclipse intellisense feature to explore the various properties and methods that can be accessed via the IConnection interface.

Compile & Build

To build the plugin open a shell prompt and navigate to the project folder where the pom.xml file resides. Now execute the following command in the terminal:

mvn install -Dgpg.skip=true

If there are no errors, the result of the command will be a folder called target in the project directory and it will contain the output file – CustomApiPlugin.jar

Deploying the plugin

To deploy the folder move the plugin file to the ant media server plugins directory:

cp target/CustomApiPlugin.jar /usr/local/antmedia/plugins

After copying the jar restart the server so that it can detect and load the newly added classes from your plugin file.

Testing the plugin

To execute the REST API call that we just added, navigate to http://localhost:5080/LiveApp/rest/sample-plugin/connections

This will return a JSON array of connection information of clients connected to the LiveApp application. If you want to show more information about the connection then you can add more attributes to the class ConnectionInfo.java and pull in values from the IConnection class.

Repository

You can find the source code on our GitHub repository.