# REST API

## Overview

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

{% hint style="warning" %}
다음과 같은 제한 사항 및 고려사항이 있습니다.

* API를 통해 App 또는 Output Profile의 설정을 추가/변경/삭제하면 해당 애플리케이션이 재시작됩니다. 이로 인해 해당 애플리케이션에 연결된 모든 세션이 종료됩니다.
* `Server.xml`에 정의된 VirtualHost 설정은 API를 통해 수정할 수 없습니다. 이 규칙은 해당 VirtualHost 내부의 Application/OutputStream 등에도 동일하게 적용됩니다. 따라서 `Server.xml`에 정의된 리소스에 대해 POST/PUT/DELETE API를 호출하면 403 Forbidden 오류가 발생합니다.
  {% endhint %}

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

## Setup API Server

### Port Binding

API 서버의 포트는 `<Bind><Managers><API>`에서 설정할 수 있습니다. `<Port>`는 암호화되지 않은 포트이며, `<TLSPort>`는 보안 포트입니다. TLSPort를 사용하려면 [Managers](/guide/ko-kr/features/rest-api.md#managers)에 TLS 인증서를 설정해야 합니다.

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

### Managers

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

```xml
<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 엔드포인트는 다음과 같은 형식으로 제공됩니다.

> <mark style="color:blue;">Method</mark> <http://API.Server.Address\\[:Port]/><mark style="color:orange;">v1</mark>/<mark style="color:purple;">Resource</mark>&#x20;
>
> <mark style="color:blue;">Method</mark> <https://API.Server.Address\\[:TLSPort]/><mark style="color:orange;">v1</mark>/<mark style="color:purple;">Resource</mark>

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

### Action

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

> <mark style="color:blue;">POST</mark> <http://host/v1/resource><mark style="color:green;">:{action name}</mark>

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

> <mark style="color:blue;">POST</mark> http\://-/v1/vhosts/{vhost}/apps/{app}/streams/{stream}:<mark style="color:green;">sendEvent</mark>

### Document format

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

<details>

<summary><mark style="color:blue;">METHOD</mark> /v1/&#x3C;API_PATH></summary>

#### Header

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

```http
Header-Key: Value

# Header-Key
    Description
```

#### Body

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

{% code overflow="wrap" %}

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

{% endcode %}

</details>

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

<details>

<summary><mark style="color:blue;">HTTP_Status_Code</mark> Code_Description</summary>

#### **Header**

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

```http
Header-Key: Value
```

#### **Body**

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

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

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

</details>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://ovenmediaengine-enterprise.gitbook.io/guide/ko-kr/features/rest-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.