POST만? 이 말도 안 되는 API 설계 논쟁을 끝내자

최근 "POST만" 사용하여 API를 설계할지에 대한 논의가 나의 관심을 끌었습니다. 이 논쟁을 조사한 후, 사람들 사이에서 논쟁하는 문제가 의미 없을 뿐만 아니라, 많은 개발자들이 API 설계의 본질을 잘못 이해하고 있다는 사실을 알게 되었습니다. 오늘은 API 설계의 핵심 아이디어를 깊이 탐구하고 왜 이 논쟁이 처음부터 존재해서는 안 되는지를 살펴보겠습니다.

"POST만"에 대한 오해#

"POST만"을 사용하여 RESTful API 사양을 대체하자고 주장하는 개발자들은 분명히 API 설계의 가장 중요한 점을 이해하지 못한 것입니다. 그들의 주장은 주로 다음과 같습니다:

1. 설계 단순화: 하나의 메소드가 모든 것을 처리할 수 있음
2. 보안: POST 매개변수가 URL에 나타나지 않음
3. 유연성: POST는 어떤 데이터 구조도 전송할 수 있음

처음에는 이러한 주장이 일리가 있어 보일 수 있습니다. 하지만 실제로 이 견해는 HTTP 메소드 선택과 API 설계 스타일을 혼동하는 것으로, 두 가지 다른 수준의 문제입니다. POST는 HTTP 프로토콜의 하나의 메소드일 뿐이며, REST는 API 설계의 한 가지 스타일입니다.

API 설계의 본질#

특정 API 스타일을 논의하기 전에, 우리는 API 설계의 핵심 목적이 무엇인지 이해해야 합니다. 좋은 API는:

1. 명확하고 이해하기 쉬워야 합니다: 다른 개발자들(미래의 나 본인 포함)이 각 엔드포인트의 목적을 직관적으로 이해할 수 있어야 합니다.
2. 일관적이어야 합니다: 학습 비용을 줄이기 위해 일정한 사양을 따릅니다.
3. 확장 가능해야 합니다: 버전 컨트롤 및 기능 확장을 쉽게 수행할 수 있어야 합니다.
4. 효율적이어야 합니다: 성능 및 자원 사용 측면에서 효율성을 고려합니다.

RESTful API: 단순한 HTTP 메소드 선택 이상의 것#

RESTful API는 많은 API 설계 스타일 중 하나로, 리소스와 리소스에 대한 작업에 중점을 둡니다. 간단한 블로그 시스템을 예로 들어 RESTful API 설계 방법을 살펴보겠습니다:

1. 모든 글을 가져오기:

2. 특정 글 가져오기:

3. 새로운 글 작성:

4. 글 업데이트:

5. 글 삭제:

이 예제에서 볼 수 있는 것은:

• API는 "article" 리소스를 중심으로 설계되었습니다.
• 서로 다른 HTTP 메소드를 사용하여 서로 다른 작업을 나타냅니다.
• URL 구조는 명확하여 어떤 리소스에 대해 작업을 수행하는지 나타냅니다.

이 설계 접근 방식은 API를 더 직관적이고 자기 설명적으로 만들어, 개발자들이 각 엔드포인트의 기능을 쉽게 이해할 수 있게 합니다.

RPC: "POST만"의 API 스타일 이해#

RPC(원격 프로시저 호출) 스타일 API 설계의 목표는 원격 서비스 호출을 로컬 함수 호출처럼 간단하게 보이도록 하는 것입니다.

흥미롭게도 "POST만"을 주장하는 사람들은 사실 RPC 스타일을 설명하고 있다는 것을 깨닫지 못할 수도 있습니다.

RESTful API와 비교하여, RPC는 리소스보다 작업 자체에 더 중점을 둡니다. 이것이 RPC 스타일 API가 일반적으로 "동사 + 명사" 형태를 사용하는 이유입니다. 예를 들어 getProduct(productId) 또는 createUser(userData)입니다.

많은 RPC 구현에서, 모든 작업은 일반적으로 동일한 엔드포인트로 POST 요청을 통해 전송되며, 요청 본문에서 특정 작업과 매개변수를 지정합니다. 이것이 바로 "POST만"의 아이디어가 사실 REST보다 RPC에 더 가깝다는 이유입니다.

예를 들어, HTTP 기반의 RPC 스타일 "상품 가져오기" 요청은 다음과 같습니다:

현대적인 RPC 프레임워크, 예를 들어 gRPC는 더 강력하고 효율적인 구현을 제공합니다. 이를 사용하여 RPC 스타일을 예시로 들어보겠습니다:

먼저 서비스와 메시지 형식을 정의합니다(Protocol Buffers 사용):

그 다음, Node.js 클라이언트에서 이 서비스를 사용하는 것은 로컬 함수 호출만큼 간단합니다:

이 RPC 스타일 예제에서 우리는 다음을 볼 수 있습니다:

1. 서비스 정의는 사용 가능 작업을 명확히 나열합니다(이 간단한 예제에서는 GetArticle과 CreateArticle).
2. 각 작업은 명확하게 정의된 요청 및 응답 유형을 가집니다.
3. 클라이언트 코드가 로컬 비동기 함수 호출처럼 보이며, await를 사용하여 결과를 기다리는데, 이는 네트워크 통신의 복잡성을 더욱 숨깁니다.
4. 수동으로 HTTP 요청을 구성하거나 JSON 응답을 구문 분석할 필요가 없습니다.

기본적으로 여전히 HTTP/2를 전송 프로토콜로 사용할 수 있지만, RPC 프레임워크(gRPC 등)는 개발자에게 원격 호출이 로컬 함수 호출처럼 보이도록 하는 추상화 계층을 제공합니다.

따라서 "POST만"과 RESTful API에 대한 대부분의 논쟁은 본질적으로 이 두 API 스타일: REST와 RPC에 대한 논의여야 합니다. 그러나 중요한 것은 이 두 스타일 모두 각기 적용 가능한 시나리오가 있으며, 선택은 개인적인 취향이 아닌 프로젝트의 특정 요구사항에 기반해야 한다는 점입니다.

REST vs RPC: 절대적 우열은 없다#

이제 REST와 RPC의 차이를 이해했으니, 각각의 적용 가능한 시나리오를 살펴보겠습니다:

1. REST는 다음에 적합합니다:
   • 리소스지향 애플리케이션(콘텐츠 관리 시스템, 블로그 플랫폼, 전자상거래 웹사이트 등)
   • 캐시 지원이 잘 되는 시나리오(GET 요청은 자연스럽게 캐시 가능)
   • HTTP 의미 체계를 활용하려는 프로젝트(적절한 상태 코드를 사용하는 등)
   • 발견 가능성과 자체 설명이 좋은 공용 API
2. RPC는 다음에 적합합니다:
   • 작업지향 애플리케이션(복잡한 데이터 처리 작업, 워크플로 제어 등)
   • 고성능 및 저지연을 요구하는 시스템(실시간 거래 시스템 등)
   • 내부 마이크로서비스 간 통신(매개변수 전달이 더 유연할 수 있음)
   • 작업이 단순히 CRUD(생성, 읽기, 업데이트, 삭제) 작업으로 매핑될 수 없는 경우

스타일 선택은 특정 요구 사항에 기반해야 합니다. 어떤 경우에는 동일한 시스템 내에서 이 두 스타일을 혼합하여 다른 부분의 요구를 충족시킬 수도 있습니다.

결론#

1. API 설계의 핵심은 명확성, 일관성, 확장성 및 효율성에 있으며, 특정 메소드나 스타일에 집착하는데 있지 않습니다.
2. RESTful과 RPC 모두 성숙한 API 설계 패러다임이며, 그 선택은 개인의 취향이 아닌 프로젝트의 요구 사항에 따라야 합니다.
3. "POST만"을 사용하기로 결정했다면, API를 RPC 스타일에 따라 설계하십시오. RESTful처럼, 이것도 업계에서 널리 사용되는 API 사양이지만 적절한 시나리오에서 사용해야 합니다.
4. 표면적인 기술적 세부 사항에 현혹되지 마십시오. 정말 중요한 것은 API가 사용자와 비즈니스 요구를 효과적으로 충족할 수 있는지 여부입니다.
5. API를 설계할 때, 어떤 HTTP 메소드를 사용할지에 대해 집착하기보다는 리소스 모델, 비즈니스 로직, 사용자 요구에 대해 더 많은 시간을 할애하십시오.

더 이상의 무의미한 논쟁에서 벗어나 진정으로 훌륭한 API 설계에 집중합시다. 결국, 기술은 문제를 해결하기 위한 것이지, 문제를 만드는 것이 아닙니다.