[웹 API 디자인] 8. 리소스가 포함되지 않은 응답은 어떻게 처리해야 할까?

리소스가 포함되지 않은 응답은 어떻게 처리해야 할까?

리소스와 관련이 없는 응답을 보내는 API 호출은 도메인에 따라 흔하지 않습니다. 금융 서비스, 통신 서비스 및 일부 자동차 분야에서 볼 수 있습니다.

다음과 같은 작업은 “리소스” 응답이 아닐 수 있다는 신호입니다.

Calculate
Translate
Convert

예를 들어, 누군가가 얼마나 세금을 내야 하는지를 간단하게 계산하거나, 자연어 번역 (요청 시 한 언어, 응답 시 다른 언어)을 수행하거나, 한 통화를 다른 통화로 변환하는 등의 간단한 알고리즘 계산이 필요한 경우가 있습니다. 이러한 경우 데이터베이스에서 반환되는 자원이 없습니다.

이러한 경우에는 다음과 같이 처리합니다:

API 디자인에서 이해하기 쉬운 URI를 만들기 위해 명사보다는 동사를 사용해야 합니다.

예를 들어, 100 유로를 중국 위안으로 변환하는 API:

/convert?from=EUR&to=CNY&amount=100

이러한 “비-리소스” 시나리오에서는 어떤 작업이 수행되어 응답이 생성되기 때문에 API 문서에서 명확하게 구분하도록 해야 합니다.

이러한 경우를 위해 문서에서 별도의 섹션을 나누어 동사를 사용하는 것이 좋습니다. 즉, 직접 리소스를 반환하지 않고 어떤 작업을 수행하여 응답을 생성하는 경우를 명확하게 구분할 수 있도록 해야 합니다.