REST vs GraphQL vs RPC: 작은 프로젝트의 API 스타일 선택과 실전 설계 팁

1. API 스타일보다 먼저 정할 것

API 선택은 유행보다 클라이언트와 서버의 변경 경계를 정하는 일에 가깝습니다. 화면이 하나이고 프론트엔드와 백엔드를 함께 바꾸는 프로젝트라면, 거대한 추상화보다 호출 흐름이 눈에 잘 보이는 방식이 유리합니다.

클라이언트가 몇 종류인가

웹 브라우저 하나만 상대한다면 서버 액션이나 단순한 REST 엔드포인트로도 충분한 경우가 많습니다. 이후 모바일 앱, 외부 파트너, 공개 API가 추가될 예정이라면 처음부터 리소스와 권한 경계를 분리해 두는 편이 안전합니다.

조코헌트에 출시된 프로덕트 258개를 보면 웹 서비스가 44%, AI 도구가 42%, 개발자 도구가 23%입니다. 제품 유형은 달라도 초기에는 한 명이 여러 화면과 서버 로직을 함께 관리한다는 공통점이 있습니다. API 선택도 확장 가능성만큼 현재의 관리 비용을 봐야 합니다.

데이터가 어떻게 바뀌는가

게시글, 프로젝트, 댓글처럼 명확한 리소스가 중심이면 REST의 구조가 자연스럽습니다. 한 화면에서 여러 리소스를 조합해 복잡한 조회를 반복한다면 GraphQL을 검토할 수 있습니다. 반대로 초대 보내기, 결제 취소, 문서 생성처럼 동작 자체가 중심이면 RPC가 읽기 쉽습니다.

2. 세 가지 스타일을 같은 질문으로 비교하기

REST: 리소스 중심의 기본값

REST는 URL과 HTTP 메서드로 대상을 표현합니다. GET /projects, POST /projects, PATCH /projects/:id처럼 팀원이 요청의 의미를 빠르게 추측할 수 있습니다.

장점은 단순한 디버깅, 익숙한 도구, 캐시 전략을 세우기 쉬운 조회 구조입니다. 단점은 화면별로 필요한 데이터를 맞추다 보면 엔드포인트가 늘어나거나 여러 번 요청해야 할 수 있다는 점입니다. 작은 CRUD 서비스라면 이 단점보다 예측 가능성이 더 큰 경우가 많습니다.

GraphQL: 조회 조합이 복잡할 때

GraphQL은 하나의 스키마를 바탕으로 클라이언트가 필요한 필드를 질의합니다. 대시보드처럼 사용자, 프로젝트, 활동 기록을 한 화면에서 조합하거나 다양한 클라이언트가 서로 다른 필드를 요구할 때 강점이 있습니다.

다만 스키마·권한·쿼리 비용·캐싱을 함께 설계해야 합니다. 단순한 화면 몇 개를 위해 도입하면 학습해야 할 개념만 늘어날 수 있습니다. 특히 어떤 쿼리가 비싼지 관찰할 장치가 없다면 성능 문제를 뒤늦게 발견하기 쉽습니다.

RPC: 행동을 명확하게 표현하기

RPC는 리소스보다 작업을 중심으로 이름을 짓습니다. createInvite, archiveProject, regenerateSummary처럼 서버에서 일어나는 행동이 이름에 드러납니다.

도메인 명령이 많은 제품에서는 REST의 동사·명사 조합을 억지로 만들지 않아도 됩니다. 대신 명령의 입력, 권한, 중복 실행 처리, 성공 결과를 일관된 형식으로 정해야 합니다. 프론트와 서버를 한 저장소에서 함께 관리하는 프로젝트라면 서버 액션도 같은 사고방식으로 사용할 수 있습니다.

3. 작은 프로젝트의 선택 기준

상황	우선 검토할 방식	이유
CRUD와 단일 웹 클라이언트	REST 또는 서버 액션	구조가 단순하고 추적이 쉬움
여러 클라이언트와 복합 조회	GraphQL	화면별 데이터 조합에 유연함
작업·명령 중심 도메인	RPC 또는 서버 액션	의도가 함수 이름에 드러남
공개 API와 외부 연동	REST	문서화와 도구 호환을 고려하기 쉬움

기본값을 정하고 예외만 기록하기

결정이 어렵다면 기본값을 하나 정하세요. 예를 들어 웹 앱 하나 + CRUD 중심이면 REST 또는 서버 액션으로 시작하고, 다음 조건이 생길 때만 바꿉니다.

같은 데이터를 여러 클라이언트가 서로 다르게 조합해야 한다.
엔드포인트 수보다 조회 스키마 관리가 더 단순해진다.
도메인의 핵심이 리소스보다 명령과 작업이다.

이 결정 기준은 모놀리식으로 시작하라에서 다룬 운영 복잡도 관리와도 연결됩니다. 지금 필요한 경계와 미래의 가능성을 분리해 생각하면 과설계를 줄일 수 있습니다.

4. 선택한 방식보다 중요한 실전 설계

입력과 오류를 먼저 고정하기

성공 응답보다 입력 검증과 오류 형식이 오래 유지됩니다. 필수 필드, 문자열 길이, 권한 부족, 존재하지 않는 대상, 중복 요청을 먼저 정의하세요. 오류에는 사용자가 이해할 메시지와 개발자가 추적할 수 있는 안정적인 코드가 함께 있으면 좋습니다.

목록 API에는 경계를 두기

목록 조회는 페이지 크기, 정렬 기준, 필터 규칙을 명시하고 기본값을 코드에 남기세요. 무제한 조회는 초기에는 편해 보여도 데이터가 쌓이면 비용과 응답 시간이 예측하기 어려워집니다. GraphQL이라면 필드 선택의 자유만큼 깊이와 비용 제한도 함께 검토해야 합니다.

인증·권한을 핸들러 밖에서도 확인하기

로그인 여부만 확인하고 소유권 검사를 빠뜨리는 실수가 흔합니다. 이 사용자가 이 프로젝트를 수정할 수 있는가를 각 변경 작업의 서버 경계에서 검증하세요. 인증 구조를 정리할 때는 로그인 설계 결정 트리를 함께 참고할 수 있습니다.

5. 나중에 바꾸기 쉽게 시작하는 법

처음부터 세 스타일을 섞어 쓰기보다 도메인별 규칙을 문서 한 장에 적어두세요. 예를 들면 조회는 REST, 상태 변경은 서버 액션, 외부 공개는 별도 REST처럼 선택 이유와 예외를 기록합니다.

핵심 로직을 HTTP 핸들러 안에 전부 넣지 말고, 입력 검증·권한 확인·도메인 작업을 나눠두면 스타일을 바꾸기도 수월합니다. AI 코딩 도구를 쓴다면 이 규칙을 AI 코딩 도구에 컨텍스트 잘 주는 법처럼 프로젝트 규칙 파일에 남겨 반복 생성되는 코드의 방향도 맞춰주세요.

결론은 간단합니다. 작은 프로젝트에서는 가장 많은 문제를 해결하는 API가 아니라, 혼자서 가장 오래 이해할 수 있는 API가 좋은 출발점입니다. 복잡성이 실제로 나타난 뒤에 GraphQL이나 별도 RPC 계층을 추가해도 늦지 않습니다.

이 글의 목차