REST API

Overview

OME에서 제공하는 REST API를 사용하면 VirtualHost 및 Application/Stream과 같은 설정을 조회하거나 변경할 수 있습니다.

다음과 같은 제한 사항 및 고려사항이 있습니다.

• API를 통해 App 또는 Output Profile의 설정을 추가/변경/삭제하면 해당 애플리케이션이 재시작됩니다. 이로 인해 해당 애플리케이션에 연결된 모든 세션이 종료됩니다.

• Server.xml에 정의된 VirtualHost 설정은 API를 통해 수정할 수 없습니다. 이 규칙은 해당 VirtualHost 내부의 Application/OutputStream 등에도 동일하게 적용됩니다. 따라서 Server.xml에 정의된 리소스에 대해 POST/PUT/DELETE API를 호출하면 403 Forbidden 오류가 발생합니다.

기본적으로 OvenMediaEngine의 API Server는 비활성화되어 있으므로, API를 사용하려면 아래 설정이 필요합니다.

Setup API Server

Port Binding

API 서버의 포트는 <Bind><Managers><API>에서 설정할 수 있습니다. <Port>는 암호화되지 않은 포트이며, <TLSPort>는 보안 포트입니다. TLSPort를 사용하려면 Managers에 TLS 인증서를 설정해야 합니다.

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

Managers

API 서버를 사용하려면 포트 바인딩뿐만 아니라 <Managers> 설정도 함께 구성해야 합니다.

<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

<Names>에 API 서버 접근을 허용할 도메인 또는 IP를 설정합니다. *를 설정하면 모든 주소에서 접근이 가능합니다. TLS 포트를 사용하려면 <TLS>에 인증서를 설정해야 합니다.

AccessToken

API 서버는 HTTP Basic 인증 방식을 사용하여 클라이언트를 인증합니다. AccessToken은 base64 인코딩 이전의 평문 인증 문자열입니다. user-id:password 형식으로 설정하면 표준 브라우저에서 인증을 사용할 수 있지만 필수는 아닙니다.

HTTP Basic 인증에 대한 자세한 내용은 아래 URL을 참고하시기 바랍니다.

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

CrossDomains

API 서버에서 CORS를 활성화하려면 해당 설정을 추가할 수 있습니다. 모든 도메인을 허용하려면 *를 사용할 수 있습니다. https://와 같이 스킴이 포함된 경우 해당 스킴만 허용되며, *.ovenmedialabs.com과 같이 스킴이 없는 경우 모든 스킴이 허용됩니다.

API Request

API 엔드포인트는 다음과 같은 형식으로 제공됩니다.

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

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

OvenMediaEngine은 GET, POST, DELETE 메서드를 지원하며, 리소스 유형에 따라 PATCH도 지원합니다. 자세한 API 명세는 이 챕터의 하위 문서를 참고하시기 바랍니다.

Action

OvenMediaEngine의 REST API에서는 다음과 같은 형식으로 Action을 제공합니다.

POST http://host/v1/resource:{action name}

예를 들어 LLHLS 스트림에 ID3 Timedmeta 이벤트를 전송하는 Action은 다음과 같은 엔드포인트로 제공됩니다.

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

Document format

이 API 레퍼런스 문서에서는 API 엔드포인트를 다음과 같이 표현합니다. 모든 엔드포인트에서 scheme://Host[:Port]는 생략되어 있습니다.

METHOD /v1/<API_PATH>

Header

필수 헤더 값이 설명됩니다.

Header-Key: Value

# Header-Key
    Description

Body

요청 본문의 내용을 설명합니다. 모든 API의 Body는 JSON 형식으로 구성되며, Content-Type은 항상 application/json입니다(문서에서는 생략될 수 있음).

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

API 응답 역시 다음과 같은 형식으로 제공됩니다.

HTTP_Status_Code Code_Description

Header

응답 헤더에 대한 설명입니다.

Header-Key: Value

Body

응답 본문의 내용을 설명합니다. 모든 응답 본문은 JSON 콘텐츠로 구성됩니다. 따라서 Content-Type 헤더 값은 항상 application/json이며, 문서에서는 생략할 수 있습니다.

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

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