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 Media Node info: GET /pro/media-nodes/<MEDIA_NODE_ID>
- Get all Media Nodes info: GET /pro/media-nodes
- Add new Media Node: POST /pro/media-nodes
- Remove Media Node: DELETE /pro/media-nodes/<MEDIA_NODE_ID>
- Modify Media Node: PATCH /pro/media-nodes/<MEDIA_NODE_ID>
- Force Media Nodes autodiscovery: PUT /pro/media-nodes
- Restart OpenVidu Pro: POST /pro/restart
- Get OpenVidu Pro active configuration: GET /pro/config
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 | 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": 15.55, "status": "running"} |
Query params
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?sessions=false&extra-info=false
Returned JSON
id
: Media Node unique identifier. Use it to perform other REST operations on this Media NodeenvironmentId
: Media Node identifier dependent on the deployment environment. For example, an AWS EC2 machine id if the cluster is deployed in AWSip
: Media Node IPuri
: Media Node URI endpoint. This is the URI where OpenVidu Server will establish a connection with the Media Nodeconnected
: 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 NodeconnectionTime
: 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 ifconnected
is falsesessions
: 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 paramsessions
is set to trueload
: CPU load of the Media Node (decimal number between 0.00 and 100.00)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 paramextra-info
is set to true (for advanced users, subject to change)
HTTP responses
200
: the Media Node information has been successfully retrieved404
: no Media Node exists for the passed MEDIA_NODE_ID
GET /pro/media-nodes
🔗
LIST MEDIA NODES INFO | PARAMETERS |
---|---|
Operation | GET |
URL | https://<YOUR_OPENVIDUSERVER_IP>/pro/media-nodes |
Query params | 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": 15.55} ]} |
Query params
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?sessions=false&extra-info=false
Returned JSON
numberOfElements
: total number of registered Media Nodescontent
: 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
200
: Media Nodes information has been successfully retrieved
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 reachesrunning
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 for On Premises deployments) : 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 On Premises deployments. For other deployment environments a new Media Node will be automatically launched ignoring parameteruri
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 reachesrunning
status.
HTTP responses
200
: the Media Node has been successfully added400
: problem with some body parameter404
: 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 Server501
: the cluster is deployed On Premises and nouri
parameter was passed in the body request.502
: the process of launching a new Media Node instance failed. This won't ever happen for On Premises deployments, where instances require manual launching
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 reachesterminated
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 reasonmediaServerDisconnect
(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 status409
. If the Media Node has no ongoing sessions, then OpenVidu Pro will remove it immediately, returning status204
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 towaiting-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 be202
if this operation changed the Media Node towaiting-idle-to-terminate
status and204
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 parameterdeletion-strategy
is set towhen-no-sessions
, then it means that the Media Node to be deleted has ongoing sessions inside of it. Media Node status has been set towaiting-idle-to-terminate
204
: the Media Node was successfully removed404
: no Media Node exists for the passed MEDIA_NODE_ID409
: if query parameterdeletion-strategy
is set toif-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.502
: error while terminating the Media Node instance. This won't ever happen for On Premises deployments, where instances require manual shut down
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
canceled
(fromlaunching
status),launching
(fromcanceled
status),waiting-idle-to-terminate
(fromrunning
status),running
(fromwaiting-idle-to-terminate
) andterminating
(from bothrunning
andwaiting-idle-to-terminate
). Visit Media Node statuses to understand the Media Node lifecycle
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 modified204
: the Media Node has not been modified because its status was the same as the provided through body parameters400
: problem with some body parameter. This means the Media Node cannot transition from its current status to the indicated one in thestatus
request body parameter404
: no Media Node exists for the passed MEDIA_NODE_ID
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 Nodescontent
: 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 completed405
: autodiscovery process is not possible. This may happen if OpenVidu Pro cluster environment is set toon_premise
and no autodiscover script is available.
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_SESSIONS_GARBAGE_INTERVAL": 900, "OPENVIDU_SESSIONS_GARBAGE_THRESHOLD": 3600, "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 configuration properties to be applied on the restart process. These include OpenVidu CE configuration properties and OpenVidu Pro configuration properties (bear in mind not all of them are available for change using this method). All of them are optional. Not all properties can be modified this way. Others require a manual update. The complete list of available properties to be modified with this method is listed below. Visit the configuration docs for a detailed description of each one of them.
- OPENVIDU_CDR (optional boolean)
- OPENVIDU_RECORDING (optional boolean)
- OPENVIDU_RECORDING_PATH (optional string)
- OPENVIDU_RECORDING_PUBLIC_ACCESS (optional boolean)
- OPENVIDU_RECORDING_NOTIFICATION (optional string)
- OPENVIDU_RECORDING_CUSTOM_LAYOUT (optional string)
- OPENVIDU_RECORDING_AUTOSTOP_TIMEOUT (optional number)
- OPENVIDU_WEBHOOK (optional boolean)
- OPENVIDU_WEBHOOK_ENDPOINT (optional string)
- OPENVIDU_WEBHOOK_HEADERS: (optional array of strings)
- OPENVIDU_WEBHOOK_EVENTS (optional array of strings)
- OPENVIDU_STREAMS_VIDEO_MAX_RECV_BANDWIDTH (optional number)
- OPENVIDU_STREAMS_VIDEO_MIN_RECV_BANDWIDTH (optional number)
- OPENVIDU_STREAMS_VIDEO_MAX_SEND_BANDWIDTH (optional number)
- OPENVIDU_STREAMS_VIDEO_MIN_SEND_BANDWIDTH (optional number)
- OPENVIDU_SESSIONS_GARBAGE_INTERVAL (optional number)
- OPENVIDU_SESSIONS_GARBAGE_THRESHOLD (optional number)
- OPENVIDU_PRO_CLUSTER_ID (optional string)
- OPENVIDU_PRO_CLUSTER_MEDIA_NODES (optional number)
- OPENVIDU_PRO_CLUSTER_PATH (optional string)
- OPENVIDU_PRO_CLUSTER_AUTOSCALING (optional boolean)
- OPENVIDU_PRO_CLUSTER_AUTOSCALING_MAX_NODES (optional number)
- OPENVIDU_PRO_CLUSTER_AUTOSCALING_MIN_NODES (optional number)
- OPENVIDU_PRO_CLUSTER_AUTOSCALING_MAX_LOAD (optional number)
- OPENVIDU_PRO_CLUSTER_AUTOSCALING_MIN_LOAD (optional number)
- OPENVIDU_PRO_STATS_MONITORING_INTERVAL (optional number)
- OPENVIDU_PRO_STATS_WEBRTC_INTERVAL (optional number)
HTTP responses
200
: the restarting process has been initialized. All properties are valid and OpenVidu Server should restart properly400
: 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. For those parameters for which no value has been provided, the previous existing will be used. The new applied values will be stored in disk in your 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.13.0", "OPENVIDU_SERVER_DEPENDENCY_VERSION": "2.13.0", "DOMAIN_OR_PUBLIC_IP": "test.openvidu.io", "HTTPS_PORT": 443, "OPENVIDU_PUBLICURL": "https://test.openvidu.io/", "KMS_URIS": [], "OPENVIDU_CDR": true, "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_SESSIONS_GARBAGE_INTERVAL": 900, "OPENVIDU_SESSIONS_GARBAGE_THRESHOLD": 3600, "OPENVIDU_RECORDING": true, "OPENVIDU_RECORDING_VERSION": "2.9.0", "OPENVIDU_RECORDING_PATH": "/opt/openvidu/recordings/", "OPENVIDU_RECORDING_PUBLIC_ACCESS": false, "OPENVIDU_RECORDING_NOTIFICATION": "publisher_moderator", "OPENVIDU_RECORDING_CUSTOM_LAYOUT": "/opt/openvidu/custom-layout/", "OPENVIDU_RECORDING_AUTOSTOP_TIMEOUT": 120, "OPENVIDU_WEBHOOK": false, "OPENVIDU_PRO_STATS_MONITORING_INTERVAL": 0, "OPENVIDU_PRO_STATS_WEBRTC_INTERVAL": 5, "OPENVIDU_PRO_CLUSTER_ID": "TEST_CLUSTER_ID", "OPENVIDU_PRO_CLUSTER_ENVIRONMENT": "docker", "OPENVIDU_PRO_CLUSTER_MEDIA_NODES": 1, "OPENVIDU_PRO_CLUSTER_AUTOSCALING": false, "OPENVIDU_PRO_CLUSTER_PATH": "/opt/openvidu/cluster/", "OPENVIDU_PRO_ELASTICSEARCH": true, "OPENVIDU_PRO_ELASTICSEARCH_HOST": "http://localhost:9200", "OPENVIDU_PRO_ELASTICSEARCH_VERSION": "7.6.2", "OPENVIDU_PRO_KIBANA": true, "OPENVIDU_PRO_KIBANA_HOST": "http://localhost:5601", "OPENVIDU_PRO_KIBANA_VERSION": "7.6.2"} |
Returned JSON
VERSION
: version of OpenVidu Server ProOPENVIDU_SERVER_DEPENDENCY_VERSION
: version of OpenVidu Server CE upon which this version of OpenVidu Server Pro is built on- Rest of properties: current active values for the configuration properties of OpenVidu Server Pro. These properties are mostly common to method GET /config of OpenVidu Server CE. Some of them are unique for OpenVidu Server Pro