REST API Pro


OpenVidu Pro provides all of OpenVidu CE 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/media-nodes/<MEDIA_NODE_ID>

GET MEDIA NODE INFO PARAMETERS
Operation GET
URL https://<YOUR_OPENVIDUSERVER_IP>/pro/media-nodes/<MEDIA_NODE_ID>
Query params load, sessions, extra-info
Headers Authorization: Basic EncodeBase64(OPENVIDUAPP:<YOUR_SECRET>)
Content-Type: application/x-www-form-urlencoded
Sample return {"id": "kms_RicdrF9x", "environmentId": "5372e1c954fd54c13706f476236", "ip": "172.17.0.4", "uri": "ws://172.17.0.4:8888/kurento", "connected": true, "connectionTime": 1583753233620, "sessions": [], "load": 0.0, "status": "running"}

Query params

  • load (optional boolean, default to false) : whether to return Media Node 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 Node information or not. Only sessions hosted in this Media Node will be retrieved. Session information has same format as returned by method GET /api/sessions/<SESSION_ID>
  • extra-info (optional boolean, default to false) : whether to return extra information about the Media Node or not. Only for advanced users

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

Returned JSON

  • id: Media Node unique identifier. Use it to perform other REST operations on this Media Node
  • environmentId: Media Node identifier dependent on the deployment environment. For example, an AWS EC2 machine id if the cluster is deployed in AWS
  • ip: Media Node IP
  • uri: Media Node URI endpoint. This is the URI where OpenVidu Server will establish a connection with the Media Node
  • connected: whether OpenVidu Server Pro is connected to this Media Node or not. This property may be set to false if there's an unexpected disconnection of the Media Node
  • connectionTime: when did OpenVidu Server establish the connection with the Media Node (in UTC milliseconds)
  • disconnectionTime: when did OpenVidu Server lose its connection to the Media Node (in UTC milliseconds). Only defined if connected is false
  • sessions: session information of this Media Node. 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
  • load: load of the Media Node. Only available if query param load is set to true
  • status: status of the Media Node (see Media Node statuses)
  • kurentoInfo: object with extra advanced information about this instance of Kurento Media Server (version, modules, memory usage...). Only available if query param extra-info is set to true (for advanced users, subject to change)

HTTP responses

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

GET /pro/media-nodes

LIST MEDIA NODES INFO PARAMETERS
Operation GET
URL https://<YOUR_OPENVIDUSERVER_IP>/pro/media-nodes
Query params load, sessions, extra-info
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 Nodes 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 Nodes information or not. Media Node will be retrieved. Session information has same format as returned by method GET /api/sessions/<SESSION_ID>
  • extra-info (optional boolean, default to false) : whether to return extra information about the Media Nodes or not. Only for advanced users

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

Returned JSON

  • numberOfElements: total number of registered Media Nodes
  • content: array of Media Nodes. Each object has the same structure as defined in the returned JSON of GET /pro/media-nodes/<MEDIA_NODE_ID>

HTTP responses


POST /pro/media-nodes

NEW MEDIA NODE PARAMETERS
Operation POST
URL https://<YOUR_OPENVIDUSERVER_IP>/pro/media-nodes
Query params wait
Headers Authorization: Basic EncodeBase64(OPENVIDUAPP:<YOUR_SECRET>)
Content-Type: application/json
Body {"uri": "MEDIA_NODE_URI"}
Sample return { "id": "kms_LrMRlL42", "ip": "172.17.0.5", "uri": "ws://172.17.0.5:8888/kurento", "connected": true, "connectionTime": 1583769116854, "environmentId": "489ed9c4b4d761699dc93", "status": "running" }

Query params

  • wait (optional boolean, default to false) : whether to wait until the new Media Node reaches running status or not. Setting this property to true basically makes this method synchronized. You will not receive an answer until the Media Node is properly running or an error is thrown.

Encode query params in the url like this:
https://<YOUR_OPENVIDUSERVER_IP>/pro/media-nodes?wait=true

Body parameters


  • uri (mandatory string only if openvidu.pro.cluster.mode is manual) : the websocket endpoint of a running Media Node. For a Kurento Media Server, it should be something similar to ws://media.server.ip:8888/kurento. This property is only necessary and is only taken into account if openvidu.pro.cluster.mode is set to manual. For mode auto a new Media Node will be automatically launched ignoring parameter uri

Returned JSON

Same JSON response as defined for GET /pro/media-nodes/<MEDIA_NODE_ID> (with all its query params to their default value). If query param wait is set to false, most of its properties will be null. All properties will be defined only after the Media Node reaches running status.

HTTP responses

  • 200: the Media Node has been successfully added
  • 400: problem with some body parameter
  • 404: the Media Node 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 Node was already registered in OpenVidu Server
  • 501: configuration property openvidu.pro.cluster is set to false, or is true but property openvidu.pro.cluster.mode is set to manual and no uri parameter was passed in the body request.
  • 502: the process of launching a new Media Node instance failed. Only possible if property openvidu.pro.cluster.mode is set to auto

DELETE /pro/media-nodes/<MEDIA_NODE_ID>

REMOVE MEDIA NODE PARAMETERS
Operation DELETE
URL https://<YOUR_OPENVIDUSERVER_IP>/pro/media-nodes/<MEDIA_NODE_ID>
Query params deletion-strategy
Headers Authorization: Basic EncodeBase64(OPENVIDUAPP:<YOUR_SECRET>)
Content-Type: application/x-www-form-urlencoded
Sample return Returns nothing

Query params

  • wait (optional boolean, default to false) : whether to wait until the new Media Node reaches terminated status or not. Setting this property to true basically makes this method synchronized. You will not receive an answer until the Media Node is fully terminated or an error is thrown.
  • deletion-strategy (optional string, default to "if-no-sessions") : how should OpenVidu Pro proceed with the Media Node deletion. Can be:
    • now: OpenVidu Pro will remove the Media Node immediately. All OpenVidu sessions hosted by this Media Node will be closed with reason mediaServerDisconnect (all streams, participants and recordings of all these sessions will be stopped with this same reason)
    • if-no-sessions (default value) : if there's any OpenVidu session initialized inside of this Media Node, then this operation will fail with HTTP status 409. If the Media Node has no ongoing sessions, then OpenVidu Pro will remove it immediately, returning status 204
    • when-no-sessions: if there's any OpenVidu session initialized inside this Media Node, then it will not be immediately deleted, but instead will be set to waiting-idle-to-terminate status. This status means the Media Node is under quarantine and no more sessions will be initialized inside of it. Whenever the last session of this Media Node is destroyed (no matter the reason), then it will be automatically deleted. The response status will be 202 if this operation changed the Media Node to waiting-idle-to-terminate status and 204 if there were no ongoing sessions inside the Media Node and therefore OpenVidu Pro has deleted it.

Encode query params in the url like this:
https://<YOUR_OPENVIDUSERVER_IP>/pro/media-nodes/<MEDIA_NODE_ID>?wait=false&deletion-strategy=now

HTTP responses

  • 202: if query parameter deletion-strategy is set to when-no-sessions, then it means that the Media Node to be deleted has ongoing sessions inside of it. Media Node status has been set to waiting-idle-to-terminate
  • 204: the Media Node was successfully removed
  • 404: no Media Node exists for the passed MEDIA_NODE_ID
  • 409: if query parameter deletion-strategy is set to if-no-sessions, then it means that the Media Node to be deleted has ongoing sessions inside of it. No Media Node deletion will take place at all.
  • 501: configuration property openvidu.pro.cluster is set to false. You need to enable cluster mode to be able to manage Media Nodes
  • 502: error while terminating the Media Node instance. Only possible if property openvidu.pro.cluster.mode is set to auto

PATCH /pro/media-nodes/<MEDIA_NODE_ID>

MODIFY MEDIA NODE PARAMETERS
Operation PATCH
URL https://<YOUR_OPENVIDUSERVER_IP>/pro/media-nodes/<MEDIA_NODE_ID>
Headers Authorization: Basic EncodeBase64(OPENVIDUAPP:<YOUR_SECRET>)
Content-Type: application/json
Body {"status": "MEDIA_NODE_STATUS"}
Sample return {"id": "KMS-GVM2CW", "uri": "ws://localhost:8888/kurento", "ip": "localhost", "connected": true, "connectionTime": 1562746120857, "quarantined": false}

Body parameters


  • status (mandatory string) : new desired status of the Media Node. Valid values are waiting-idle-to-terminate (from running status), running (from waiting-idle-to-terminate) and terminating (from both running and waiting-idle-to-terminate)

Returned JSON

The modified Media Node. Same JSON response as defined for GET /pro/media-nodes/<MEDIA_NODE_ID> (with all its query params to their default value)

HTTP responses

  • 200: the Media Node has been successfully modified
  • 204: the Media Node has not been modified because its status was the same as the provided through body parameters
  • 400: problem with some body parameter. This will also be the status if you try to set property status to an invalid one (launching, failed, terminated)
  • 404: no Media Node exists for the passed MEDIA_NODE_ID
  • 501: configuration property openvidu.pro.cluster is set to false. You need to enable cluster mode to be able to manage Media Nodes

PUT /pro/media-nodes

AUTODISCOVER MEDIA NODES PARAMETERS
Operation PUT
URL https://<YOUR_OPENVIDUSERVER_IP>/pro/media-nodes
Headers Authorization: Basic EncodeBase64(OPENVIDUAPP:<YOUR_SECRET>)
Sample return {"numberOfElements": 1, "content": [ "id": "kms_LrMRlL42", "ip": "172.17.0.5", "uri": "ws://172.17.0.5:8888/kurento", "connected": true, "connectionTime": 1583769116854, "environmentId": "489ed9c4b4d761699dc93", "status": "running" ]}

Returned JSON

  • numberOfElements: total number of newly autodiscovered Media Nodes
  • content: array of newly autodiscovered Media Nodes. Each object has the same structure as defined in the returned JSON of GET /pro/media-nodes/<MEDIA_NODE_ID> (with all its query params to their default value)

HTTP responses

  • 200: autodiscovery process has completed
  • 405: autodiscovery process is not possible. This may happen if OpenVidu Pro cluster environment is set to on_premise and no autodiscover script is available.
  • 501: configuration property openvidu.pro.cluster is set to false. You need to enable cluster mode to be able to manage Media Nodes

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/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