Skip to main content

REST API

Overview​

The REST APIs provided by OME allow you to query or change settings such as VirtualHost and Application/Stream.

warning

There are some limitations/considerations.

  • If you add/change/delete the settings of the App/Output Profile by invoking the API, the app will be restarted. This means that all sessions connected to the app will be disconnected.
  • VirtualHost settings in Server.xml cannot be modified through API. This rule also applies to Application/OutputStream, etc. within that VirtualHost. So, if you call a POST/PUT/DELETE API for VirtualHost/Application/OutputProfile declared in Server.xml, it will not work with a 403 Forbidden error.

By default, OvenMediaEngine's API Server is disabled, so the following settings are required to use the API.

Setup API Server​

Port Binding​

The API server's port can be set in <Bind><Managers><API>. <Port> is an unsecured port and <TLSPort> is a secured port. To use TLSPort, TLS certificate must be set in the Managers.

<Server version="8">
	...
	<Bind>
		<Managers>
			<API>
				<Port>8081</Port>
				<TLSPort>8082</TLSPort>
			</API>
		</Managers>
		...
	</Bind>
	...
</Server>

Managers​

In order to use the API server, you must configure <Managers> as well as port binding.

<Server version="8">
	<Bind>
		...
	</Bind>

	<Managers>
		<Host>
			<Names>
				<Name>*</Name>
			</Names>
			<TLS>
				<CertPath>ovenmedia_com.crt</CertPath>
				<KeyPath>ovenmedia_com.key</KeyPath>
				<ChainCertPath>ovenmedia_com_chain.crt</ChainCertPath>
			</TLS>
		</Host>
		<API>
			<AccessToken>your_access_token</AccessToken>
			<CrossDomains>
				<Url>*.ovenmedia.com</Url>
				<Url>http://*.sub-domain.ovenmedia.com</Url>
				<Url>http?://ovenmedia.*</Url>
			</CrossDomains>
		</API>
	</Managers>

	<VirtualHosts>
		...
	</VirtualHosts>
</Server>

Host​

In <Names>, set the domain or IP that can access the API server. If * is set, any address is used. In order to access using the TLS Port, a certificate must be set in <TLS>.

AccessToken​

API Server uses Basic HTTP Authentication Scheme to authenticate clients. An AccessToken is a plaintext credential string before base64 encoding. Setting the AccessToken to the form user-id:password per RFC7617 allows standard browsers to pass authentication, but it is not required.

For more information about HTTP Basic authentication, refer to the URL below.

https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication

CrossDomains​

To enable CORS on your API Server, you can add a setting. You can add * to allow all domains. If contains a scheme, such as https://, only that scheme can be allowed, or if the scheme is omitted, such as *.ovenmedia.com, all schemes can be accepted.

API Request​

API endpoints are provided in the following format.

Method http://API.Server.Address\[:Port]/v1/Resource&#x20;

Method https://API.Server.Address\[:TLSPort]/v1/Resource

OvenMediaEngine supports GET, POST, and DELETE methods, and sometimes supports PATCH depending on the type of resource. For detailed API specifications, please check the subdirectory of this chapter.

Action​

In OvenMediaEngine's REST API, action is provided in the following format.

POST http://host/v1/resource:&#x7B;action name}

For example, an action to send an ID3 Timedmeta event to an LLHLS stream is provided by the endpoint below.

POST http://-/v1/vhosts/{vhost}/apps/{app}/streams/{stream}:sendEvent

Document format​

In this API reference document, the API endpoint is described as follows. Note that scheme://Host[:Port] is omitted for all endpoints.

METHOD /v1/<API_PATH>

Describe the required header values.

Header-Key: Value

# Header-Key
    Description

Body​

Describe the request body content. The body of all APIs consists of Json content. Therefore, the Content-Type header value is always application/json, which can be omitted in the document.

{
    "requestId": "value"
}
    
# key (required)
    The description of the key/value of the body content is provided like this.

Responses from API endpoints are provided in the following format.

HTTP_Status_Code Code_Description

Header​

Description of response headers

Header-Key: Value

Body​

Description the response body content. The body of all response consists of Json content. Therefore, the Content-Type header value is always application/json, which can be omitted in the document.

{
	"statusCode": 200,
	"message": "OK",
	"response": {
	}
}

# statusCode
	Same as HTTP Status Code
# message
	A human-readable description of the response code
# response
	Response Contents