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


POST /pro/media-servers

NEW MEDIA SERVER PARAMETERS
Operation POST
URL https://<YOUR_OPENVIDUSERVER_IP>/pro/media-servers
Headers Authorization: Basic EncodeBase64(OPENVIDUAPP:<YOUR_SECRET>)
Content-Type: application/json
Body {"uri": "MEDIA_SERVER_URI"}
Sample return {"id": "KMS-GVM2CW", "uri": "ws://localhost:8888/kurento", "ip": "localhost", "connected": true, "connectionTime": 1562746120857}

Body parameters


  • uri (optional string): the websocket endpoint of the running media server. For a Kurento Media Server, it should be something similar to "ws://media.server.ip:8888/kurento".

NOTE: if no body parameter is sent in the POST request, OpenVidu Server Pro will launch a new media server instance for you

Returned JSON

  • id: media server unique identifier. Use it to perform other REST operations on this media server
  • uri: media server URI endpoint. Same value as provided in property uri of the body request
  • ip: media server IP (got from the uri)
  • connected: set to true
  • connectionTime: when did OpenVidu Server establish the connection with the media server (in UTC milliseconds)

HTTP responses

  • 200: the media server has been successfully added
  • 400: problem with some body parameter
  • 404: the media server is not within reach of OpenVidu Server. This simply means that OpenVidu cannot establish a connection with it. This may be caused by multiple reasons: wrong IP, port or path, a network problem, too strict a proxy configuration...
  • 409: the media server was already registered in OpenVidu Server
  • 501: configuration property openvidu.pro.cluster is set to false. You need to enable cluster mode to be able to manage media servers
  • 502: the process of launching a new media server instance failed. Only possible if no uri parameter was provided in the body POST request

DELETE /pro/media-servers/<MEDIA_SERVER_ID>

REMOVE MEDIA SERVER PARAMETERS
Operation DELETE
URL https://<YOUR_OPENVIDUSERVER_IP>/pro/media-servers/<MEDIA_SERVER_ID>
Query params force, dropInstance
Headers Authorization: Basic EncodeBase64(OPENVIDUAPP:<YOUR_SECRET>)
Content-Type: application/x-www-form-urlencoded
Sample return Returns nothing

Query params

  • force (optional boolean, default to false) : whether to force the media server deregistration or not. If there's any OpenVidu session initialized inside this media server and parameter force is set to false, then this operation will fail with HTTP status set to 409. If force is set to true, all OpenVidu sessions hosted by this media server will be closed with reason mediaServerDisconnect (all streams, participants and recordings of all these sessions will be stopped with that same reason)
  • dropInstance (optional boolean, default to false) : whether to terminate the instance of the media server or not.

Encode query params in the url like this:
https://<YOUR_OPENVIDUSERVER_IP>/pro/media-servers/<MEDIA_SERVER_ID>?force=true&dropInstance=false

HTTP responses

  • 204: the media server was successfully removed
  • 404: no media server exists for the passed MEDIA_SERVER_ID
  • 409: there are running sessions in this media server. If you want to avoid this error and force the disconnection of the media server closing all sessions hosted inside of it, set query param force to true
  • 501: configuration property openvidu.pro.cluster is set to false. You need to enable cluster mode to be able to manage media servers
  • 502: error while terminating the media server instance. Only possible if dropInstance query param was set to true