[Unity] Rest API 특징 및 예제

개인 프로젝트를 진행하면서 Unity에서 외부 API와 통신할 일이 생겼고,
그 방식으로 REST API를 선택했습니다.
이번 글에서는 Unity에서 REST API를 어떻게 활용했는지, 그리고 왜 이 방식이 적합했는지를 정리해보려 합니다.

(* Rest API를 설계한 과정 : https://developer-growth-history.tistory.com/101)

🤔 REST API란?

REST API는 웹 표준에 맞춘 HTTP 기반의 API 방식으로, JSON을 주고받으며 요청과 응답을 처리하는 구조이다!!

 

1. REST API 특징

1-1. 표준화된 방식이라 협업이 용이함

• REST API는 JSON 기반이라서 백엔드, 프론트엔드, Unity 모두 쉽게 연동 가능하다
• OAuth 2.0, JWT 인증 등과 쉽게 연동 가능 => 보안 구성에 유리! 

1-2. Unity에서의 높은 호환성

• WebGL에서는 HttpClient 사용 불가! ( UnityWebRequest 필수다! !)
• UnityWebRequest를 통해 모든 플랫폼에서 사용 가능
• Coroutine, async-await을 모두 지원되기 때문에 유연한 개발 가능 

1-3. 보안성과 확장성

• HTTPS 지원 + 인증 시스템 연동이 쉬움
• REST API는 Stateless(무상태성) 특성 덕분에 서버 부하가 적고, 확장성(Scaling)이 좋음

그리고 JSON 포맷을 주고받으며, HTTP 상태 코드(200, 400, 500 등)를 통해 요청 결과를 알 수도 있음! 

 

2. 실전 예제: Google Cloud STT API 사용

그럼 이제 내가 설계한 Rest API를 통해 Google STT API에 음성 데이터를 보내고, 텍스트를 받아오는 과정을 정리해보자 

 

2-1. 오디오 데이터를 Base64로 인코딩

private async UniTask<string> SendAudioToRestAPI(byte[] audioData)
{
    string base64Audio = Convert.ToBase64String(audioData);
    ...

• Google STT API는 오디오 데이터를 base64 문자열로 받아야 하므로, Unity의 byte[] 데이터를 변환

 

2-2. JSON 요청 생성 (Newtonsoft.Json)

var requestData = new
{
    config = new
    {
        encoding = "LINEAR16",
        sampleRateHertz = SampleRate,
        languageCode = "ko-KR"
    },
    audio = new
    {
        content = base64Audio
    }
};

string jsonRequest = JsonConvert.SerializeObject(requestData);

 

• 간결하고 직관적인 JSON 구조 생성
• Newtonsoft.Json의 SerializeObject를 통해 문자열(JSON)로 변환
• "config"와 "audio"는 Google Cloud STT API의 요구 포맷을 따름

 

 

2-3. 요청 옵션 설정

var options = new RestApiRequestOptions(apiKey, Defines.RequestMethod.Post)
    .SetHeader(new() { ContentType = Defines.Header.ContentType.Application_Json })
    .SetBody(requestData);

 

• Content-Type: application/json 설정은 필수
• RestApiRequestOptions는 헤더, 바디 등 요청 정보를 캡슐화하여 가독성과 재사용성 향상

* RestApiRequestOptions 클래스는
REST API 요청을 보낼 때 필요한 옵션(헤더, 바디, 인증 등) 을 한 곳에 모아 구성해주는 설정 클래스로 
코드의 가독성과 재사용성을 높이기 위한 래퍼(wrapper) 역할을 하기 위해 구현한 클래스입니다! 

여러 요청마다 반복되는 헤더 설정, Body 구성, 인증키 전달 등의 로직을 하나로 묶어 깔끔하게 관리하기 위해 구현한 것

 

 

2-4. API 서버에 비동기 요청 보내기

 

var client = new RestApiClient(options);
var transfer = await client.RequestToApiServer(ApiType.GoogleSTT);

 

• await를 사용하여 메인 스레드 블로킹 없이 비동기 처리
• ApiType.GoogleSTT는 내부적으로 URL을 enum으로 관리하는 구조

 

 

2-5. 응답 데이터 처리

var response = JsonConvert.DeserializeObject<GoogleSTTResponse>(transfer.Body);
if (response?.results == null || response.results.Length == 0)
{
    Debug.LogError("STT 응답이 없습니다.");
    return null;
}

return response.results[0].alternatives[0].transcript;

 

• 응답 JSON을 객체로 역직렬화 (GoogleSTTResponse 클래스 필요)
• 결과가 없을 경우 에러 로그 출력
• 음성 인식된 텍스트(transcript)만 추출하여 반환

 

 

STT 요청 및 응답 구성 참고 : https://cloud.google.com/speech-to-text/docs/speech-to-text-requests?hl=ko

Speech-to-Text 요청 구성  |  Cloud Speech-to-Text Documentation  |  Google Cloud

 

 

* REST API는 확장성이 뛰어나고 표준적인 방식이지만 비동기 네트워크 처리, JSON 직렬화 등 다양한 요소를 신경 써야 제대로 활용할 수 있는 방식인 것 같다

* 추후 Unity 뿐만이 아니라 .NET 프로젝트에도 사용할 수 있게 SDK/DLL로 만들 생각이 있다면 그때에는 HttpClient를 사용하는 것이 더 적절하다

 

현재는 Unity 프로젝트에서만 사용할 수 있도록 설계를 했지만,
향후 .NET 프로젝트에서도 사용할 수 있도록 더 범용적인 형태로 확장해보자.