REST API

Overview

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

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>airensoft_com.crt</CertPath>
				<KeyPath>airensoft_com.key</KeyPath>
				<ChainCertPath>airensoft_com_chain.crt</ChainCertPath>
			</TLS>
		</Host>
		<API>
			<AccessToken>your_access_token</AccessToken>
			<CrossDomains>
				<Url>*.airensoft.com</Url>
				<Url>http://*.sub-domain.airensoft.com</Url>
				<Url>http?://airensoft.*</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 *.airensoft.com, all schemes can be accepted.

API Request

API endpoints are provided in the following format.

Method http://API.Server.Address[:Port]/v1/Resource

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:{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>

Header

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