REST API Pro


OpenVidu Pro provides all of OpenVidu Community Edition REST operations, but also includes some extra REST operations of its own.

All REST operations have in common the header referred to authorization. It is implemented via Basic Auth, and it is as simple as applying Base64 encoding to the username (always "OPENVIDUAPP") and the password (your secret shared with openvidu-server). If authorization header is wrong, every call to any REST API operation will return HTTP status 401.

For example, for secret "MY_SECRET", the final valid HTTP header would be

Authorization: Basic T1BFTlZJRFVBUFA6TVlfU0VDUkVU

List of available operations



GET /pro/config

GET OPENVIDU PRO CONFIGURATION PARAMETERS
Operation GET
URL https://<YOUR_OPENVIDUSERVER_IP>/pro/config
Headers Authorization: Basic EncodeBase64(OPENVIDUAPP:<YOUR_SECRET>)
Sample return {"version": "2.10.0", "openviduPublicurl": "https://localhost:4443/", "openviduCdr": false, "maxRecvBandwidth": 1000, "minRecvBandwidth": 300, "maxSendBandwidth": 1000, "minSendBandwidth": 300, "openviduRecording": true, "openviduRecordingVersion": "2.9.0", "openviduRecordingPath": "/opt/openvidu/recordings/", "openviduRecordingPublicAccess": false, "openviduRecordingNotification": "publisher_moderator", "openviduRecordingCustomLayout": "/opt/openvidu/custom-layout/", "openviduRecordingAutostopTimeout": 120, "openviduWebhook": true, "openviduWebhookEndpoint": "http://localhost:7777/webhook/", "openviduWebhookHeaders": ["Authorization: Basic YWJjZDphYmNk"], "openviduWebhookEvents": ["recordingStatusChanged"], "openviduServerDependencyVersion": "2.10.0", "openviduProStatsMonitoringInterval": 30, "openviduProStatsWebrtcInterval": 30, "openviduProCluster": false, "openviduProClusterLoadStrategy": "streams", "kmsUris": ["ws://localhost:8888/kurento"]}

Returned JSON

  • version: version of OpenVidu Server Pro
  • openviduServerDependencyVersion: version of OpenVidu Server Community Edition upon which this version of OpenVidu Server Pro is built on
  • Rest of properties: values given to system properties on OpenVidu Server Pro launch. These properties are mostly common to method GET /config of OpenVidu Server Community Edition. Some of them are unique for OpenVidu Server Pro

POST /pro/restart

RESTART OPENVIDU PRO PARAMETERS
Operation POST
URL https://<YOUR_OPENVIDUSERVER_IP>/pro/restart/
Headers Authorization: Basic EncodeBase64(OPENVIDUAPP:<YOUR_SECRET>)
Content-Type: application/json
Body {"openvidu.secret": "MY_SECRET", "openvidu.cdr": true, "openvidu.recording": true, "openvidu.recording.public-access": true, "openvidu.recording.notification": "publisher_moderator", "openvidu.recording.path": "/opt/openvidu/recordings", "openvidu.recording.custom-layout": "/opt/openvidu/custom-layout", "openvidu.recording.autostop-timeout": 120, "openvidu.webhook": true, "openvidu.webhook.endpoint": "http://localhost:7777/webhook/", "openvidu.webhook.headers": [\"Authorization:\ Basic\ T1BFTlZJRFVBUFA6TVlfU0VDUkVU\"], "openvidu.webhook.events": ["recordingStatusChanged"], "openvidu.streams.video.max-recv-bandwidth": 1000, "openvidu.streams.video.min-recv-bandwidth": 300, "openvidu.streams.video.max-send-bandwidth": 1000, "openvidu.streams.video.min-send-bandwidth": 300, "openvidu.pro.stats.monitoring-interval": 30, "openvidu.pro.stats.webrtc-interval": 20}

Body parameters

The body of the POST request is a JSON object with the new OpenVidu system properties to be applied on the restart process. Not all of them are available, and a few are exclusive to OpenVidu Pro. The complete list of available properties is listed below


  • openvidu.secret (optional string) : new secret to secure OpenVidu Pro
  • openvidu.cdr (optional boolean) : whether to enable OpenVidu Call Detail Record or not
  • openvidu.recording (optional boolean) : whether to enable OpenVidu recording module or not
  • openvidu.recording.public-access (optional boolean) : whether to allow free http access to recorded sessions or not
  • openvidu.recording.notification (optional string) : which users should receive the recording events in the client side ("all", "publisher_moderator", "moderator" or "none")
  • openvidu.recording.path (optional string) : system path where to store the video files of recorded session
  • openvidu.recording.custom-layout (optional string) : sytem path where OpenVidu Server should look for custom recording layouts
  • openvidu.recording.autostop-timeout (optional number) : timeout in seconds for recordings to automatically stop
  • openvidu.webhook (optional boolean) : whether to enable webhook service or not
  • openvidu.webhook.endpoint (optional string) : endpoint where OpenVidu Server should sent webhook events. Mandatory if openvidu.webhook is true
  • openvidu.webhook.headers: (optional array of strings) : HTTP headers OpenVidu Server should attach to each POST message of webhook events
  • openvidu.webhook.events (optional array of strings) : events for which a POST message will be sent by OpenVidu Server webhook service
  • openvidu.streams.video.max-recv-bandwidth (optional number) : maximum video bandwidth sent from clients to OpenVidu Server, in kbps. 0 means unconstrained
  • openvidu.streams.video.min-recv-bandwidth (optional number) : minimum video bandwidth sent from clients to OpenVidu Server, in kbps. 0 means unconstrained
  • openvidu.streams.video.max-send-bandwidth (optional number) : maximum video bandwidth sent from OpenVidu Server to clients, in kbps. 0 means unconstrained
  • openvidu.streams.video.min-send-bandwidth (optional number) : minimum video bandwidth sent from OpenVidu Server to clients, in kbps. 0 means unconstrained
  • openvidu.pro.stats.monitoring-interval (optional number) : interval in seconds for CPU, memory and net usage stats gathering in OpenVidu Server Pro host machine. 0 means no gathering at all
  • openvidu.pro.stats.webrtc-interval (optional number) : interval in seconds for WebRTC stats gathering from Kurento Media Server WebRTC endpoints. 0 means no gathering at all

HTTP responses

  • 200: the restarting process has been initialized. All properties are valid and OpenVidu Server should restart properly
  • 400: there's some problem with a body parameter. The response message will provide further details

NOTES

This method will restart OpenVidu Server Pro with the new provided configuration parameters. If your have externalized OpenVidu Server Pro configuration, the new variables will be stored in the configuration file, so you will be able to restart the host without losing your new configuration


GET /pro/media-servers/<MEDIA_SERVER_ID>

GET MEDIA SERVER INFO PARAMETERS
Operation GET
URL https://<YOUR_OPENVIDUSERVER_IP>/pro/media-servers/<MEDIA_SERVER_ID>
Query params load, sessions, extraInfo
Headers Authorization: Basic EncodeBase64(OPENVIDUAPP:<YOUR_SECRET>)
Content-Type: application/x-www-form-urlencoded
Sample return {"id": "KMS-XU5ZRM", "uri": "ws://localhost:8888/kurento", "ip": "localhost", "connected": true, "connectionTime": 1562744478463, "sessions": []}

Query params

  • load (optional boolean, default to false) : whether to return media server load or not. The value will depend on configuration property openvidu.pro.cluster.load.strategy
  • sessions (optional boolean, default to false) : whether to return session information along media server information or not. Only sessions hosted in this media server will be retrieved. Session information has same format as returned by method GET /api/sessions/<SESSION_ID>
  • extraInfo (optional boolean, default to false) : whether to return extra information about the media server or not. Only for advanced users

Encode query params in the url like this:
https://<YOUR_OPENVIDUSERVER_IP>/pro/media-servers?load=true&sessions=false&extraInfo=false

Returned JSON

  • id: media server unique identifier. Use it to perform other REST operations on this media server
  • uri: media server URI endpoint. This is the URI where OpenVidu Server will establish a connection with the media server
  • ip: media server IP
  • connected: whether OpenVidu Server is connected to this media server or not. This property may be set to false if there's an unexpected disconnection of the media server
  • connectionTime: when did OpenVidu Server establish the connection with the media server (in UTC milliseconds)
  • disconnectionTime: when did OpenVidu Server lose its connection to the media server (in UTC milliseconds). Only defined if connected is false
  • load: load of the media server. Only available if query param load is set to true
  • sessions: session information of this media server. This property is an array of objects with the exact same format as the response returned by method GET /api/sessions/<SESSION_ID>. Only available if query param sessions is set to true
  • kurentoInfo: object with extra advanced information about this instance of Kurento Media Server (version, modules, memory usage...). Only available if query param extraInfo is set to true (for advanced users)

HTTP responses

  • 200: the media server information has been successfully retrieved
  • 404: no media server exists for the passed MEDIA_SERVER_ID
  • 501: configuration property openvidu.pro.cluster is set to false. You need to enable cluster mode to be able to manage media servers

GET /pro/media-servers

LIST MEDIA SERVERS INFO PARAMETERS
Operation GET
URL https://<YOUR_OPENVIDUSERVER_IP>/pro/media-servers
Query params load, sessions, extraInfo
Headers Authorization: Basic EncodeBase64(OPENVIDUAPP:<YOUR_SECRET>)
Content-Type: application/x-www-form-urlencoded
Sample return {"numberOfElements": 1, "content": [ {"id": "KMS-XU5ZRM", "uri": "ws://localhost:8888/kurento", "ip": "localhost", "connected": true, "connectionTime": 1562744478463, "load": 0} ]}

Query params

  • load (optional boolean, default to false) : whether to return media servers load or not. The value will depend on configuration property openvidu.pro.cluster.load.strategy
  • sessions (optional boolean, default to false) : whether to return session information along media servers information or not. media server will be retrieved. Session information has same format as returned by method GET /api/sessions/<SESSION_ID>
  • extraInfo (optional boolean, default to false) : whether to return extra information about the media servers or not. Only for advanced users

Encode query params in the url like this:
https://<YOUR_OPENVIDUSERVER_IP>/pro/media-servers?load=true&sessions=false&extraInfo=false

Returned JSON

  • numberOfElements: total number of registered media servers
  • content: array of media servers. Each object has the same structure as defined in the returned JSON of /pro/media-servers/<MEDIA_SERVER_ID>

HTTP responses