API 설계는 클라이언트와 서버가 어떤 규칙으로 데이터를 주고받을지 정하는 작업입니다. REST·GraphQL·RPC 중 하나가 항상 정답인 것은 아니며, 데이터 구조와 통신 대상, 성능, 운영 방식에 맞춰 선택해야 합니다.
📌 핵심 5줄 요약
1. REST는 리소스와 HTTP의 표준 동작을 중심으로 설계해 이해와 운영이 쉽습니다.
2. GraphQL은 클라이언트가 필요한 필드를 직접 요청해 여러 화면과 다양한 클라이언트에 유리합니다.
3. RPC는 원격 함수를 호출하는 방식으로 서비스 간 명확한 계약과 빠른 통신에 적합합니다.
4. 공개 웹 API와 CRUD 중심 서비스는 REST가 무난하고, 복잡한 조회 화면은 GraphQL을 검토할 수 있습니다.
5. 내부 마이크로서비스 간 통신은 RPC가 유리할 수 있지만, 디버깅·브라우저 호환성·운영 도구를 함께 확인해야 합니다.
📌 목차
01 | API 설계란 무엇인가
02 | REST의 핵심 개념
03 | REST API 설계 방법
04 | REST의 장점과 한계
05 | GraphQL의 핵심 개념
06 | GraphQL을 사용할 때의 주의점
07 | RPC와 gRPC의 구조
08 | RPC의 장점과 한계
09 | 세 방식의 핵심 비교
10 | 조회 API는 어떻게 달라지는가
11 | 쓰기 작업과 오류 설계
12 | 성능과 운영 관점 비교
13 | 상황별 선택 기준
01 | API 설계란 무엇인가
API는 애플리케이션 간 통신 규칙입니다. 요청 형식, 응답 구조, 인증 방법, 오류 표현, 데이터 변경 방식까지 포함합니다.
좋은 API는 단순히 호출에 성공하는 API가 아닙니다. 클라이언트가 예측 가능하게 사용할 수 있고, 서버 내부 구현이 바뀌어도 계약이 쉽게 깨지지 않으며, 장애 원인을 추적하기 쉬워야 합니다.
02 | REST의 핵심 개념
REST는 특정 제품이나 라이브러리 이름이 아니라 네트워크 애플리케이션을 설계하는 아키텍처 스타일입니다. 핵심은 자원을 URI로 식별하고, HTTP의 표준 메서드와 상태 코드를 활용하는 것입니다.
예를 들어 GET /users/42는 특정 사용자를 조회하고, POST /orders는 주문 생성을 요청하는 식입니다. REST의 원칙을 엄격하게 적용할수록 요청과 응답의 의미가 일관됩니다.
03 | REST API 설계 방법
URI에는 동작보다 자원을 표현하는 명사를 사용하는 편이 좋습니다. /users, /orders, /products처럼 설계하고, 동작은 HTTP 메서드로 구분합니다.
| 작업 | 일반적인 설계 |
|---|---|
| 목록 조회 | GET /users |
| 단건 조회 | GET /users/{id} |
| 생성 | POST /users |
| 전체 또는 주요 정보 수정 | PUT /users/{id} |
| 일부 필드 수정 | PATCH /users/{id} |
| 삭제 | DELETE /users/{id} |
목록 API에는 페이지네이션, 정렬, 필터 조건을 일관된 규칙으로 제공해야 합니다. 응답 필드 이름과 날짜 형식도 초기에 정하고, 임의로 엔드포인트마다 다른 표현을 사용하지 않는 것이 중요합니다.
04 | REST의 장점과 한계
REST는 HTTP와 JSON을 활용하는 경우가 많아 브라우저, 모바일 앱, 서버 등 다양한 클라이언트에서 접근하기 쉽습니다. 캐시, 프록시, 로깅, 모니터링 같은 웹 인프라와도 자연스럽게 연결됩니다.
반면 화면에 필요한 데이터가 여러 자원에 나뉘면 여러 번 요청해야 할 수 있습니다. 반대로 하나의 엔드포인트가 너무 많은 데이터를 반환하면 오버페칭이 발생합니다. 엔드포인트 수가 늘어날수록 버전 관리와 응답 형식 관리도 중요해집니다.
05 | GraphQL의 핵심 개념
GraphQL은 API를 위한 쿼리 언어이자, 정의한 타입 시스템을 바탕으로 요청을 실행하는 서버 측 런타임입니다. 클라이언트는 필요한 필드를 선택해 요청하고, 서버는 그 선택에 맞는 응답을 반환합니다.
주요 작업은 데이터를 읽는 query, 데이터를 변경하는 mutation, 실시간 이벤트를 다루는 subscription입니다. 스키마가 데이터 타입과 관계를 설명하므로 클라이언트와 서버 사이의 계약을 명확히 만들 수 있습니다.
06 | GraphQL을 사용할 때의 주의점
GraphQL은 필요한 필드만 요청할 수 있어 복잡한 화면에 편리하지만, 서버가 모든 쿼리 조합을 처리해야 합니다. 중첩 조회가 깊어지면 데이터베이스 호출이 급증하거나 응답 시간이 길어질 수 있습니다.
운영 단계에서는 쿼리 깊이와 복잡도 제한, 페이지네이션, 타임아웃, 캐시 전략, 권한 검사를 함께 설계해야 합니다. 스키마에 필드를 추가할 때는 기존 클라이언트를 깨뜨리지 않는 방식으로 확장하는 것이 일반적입니다.
07 | RPC와 gRPC의 구조
RPC는 원격 서버의 함수를 호출하듯 통신하는 방식입니다. GetUser, CreateOrder, CancelPayment처럼 수행할 작업을 서비스와 메서드로 표현합니다.
gRPC는 RPC를 구현하는 대표적인 오픈소스 프레임워크로, 서비스 정의와 메시지 구조를 바탕으로 클라이언트·서버 코드를 생성할 수 있습니다. HTTP/2 기반 통신과 스트리밍을 지원해 서비스 간 통신에 활용하기 좋습니다.
08 | RPC의 장점과 한계
RPC는 호출 가능한 메서드와 입력·출력 타입이 명확해 내부 서비스 간 계약을 엄격하게 유지하기 쉽습니다. 바이너리 직렬화와 코드 생성 방식을 사용하면 네트워크 효율과 개발 생산성을 높일 수 있습니다.
다만 브라우저에서 직접 사용하려면 별도 지원이 필요할 수 있고, HTTP 기반 REST보다 요청을 눈으로 확인하거나 단순 도구로 테스트하기 어려울 수 있습니다. 서비스 간 결합도가 높아질 가능성도 있으므로 메서드 이름과 메시지 변경 절차를 신중하게 정해야 합니다.
09 | 세 방식의 핵심 비교
| 구분 | REST | GraphQL | RPC |
|---|---|---|---|
| 중심 개념 | 리소스와 HTTP | 스키마와 필드 선택 | 서비스와 메서드 호출 |
| 응답 제어 | 엔드포인트가 결정 | 클라이언트가 선택 | 메서드 계약이 결정 |
| 적합한 환경 | 공개 웹 API, CRUD | 복잡한 화면, 다양한 클라이언트 | 내부 서비스, 고성능 통신 |
| 주요 부담 | 요청 수와 버전 관리 | 쿼리 복잡도와 캐시 | 도구 호환성과 서비스 결합 |
10 | 조회 API는 어떻게 달라지는가
상품 상세 화면에서 상품 정보, 재고, 리뷰, 추천 상품을 함께 보여준다고 가정해 보겠습니다. REST에서는 자원별 엔드포인트를 여러 번 호출하거나 화면 전용 엔드포인트를 추가할 수 있습니다.
GraphQL에서는 하나의 쿼리에서 필요한 필드를 선택할 수 있습니다. RPC에서는 GetProductPage처럼 화면 또는 업무 단위의 메서드를 정의할 수 있습니다. 어떤 방식이 좋은지는 재사용할 데이터가 많은지, 화면별 요구가 자주 바뀌는지에 따라 달라집니다.
11 | 쓰기 작업과 오류 설계
조회보다 중요한 부분은 데이터 변경입니다. 주문 생성이나 결제 요청처럼 재시도가 발생할 수 있는 작업은 중복 처리를 고려해야 합니다. 요청 식별자나 멱등성 키를 사용하면 네트워크 오류 뒤 같은 요청이 반복되는 문제를 줄일 수 있습니다.
오류 응답에는 사람이 읽을 메시지만 넣지 말고, 기계가 판단할 수 있는 안정적인 오류 코드와 필요한 세부 정보를 포함해야 합니다. 인증 실패, 권한 부족, 잘못된 입력, 리소스 없음, 서버 오류를 구분하면 클라이언트의 대응이 쉬워집니다.
12 | 성능과 운영 관점 비교
성능은 프로토콜 이름만으로 결정되지 않습니다. 데이터베이스 쿼리, 네트워크 왕복 횟수, 직렬화 방식, 캐시, 연결 관리, 서버 처리 로직이 함께 영향을 줍니다.
REST는 HTTP 캐시와 관찰 도구를 활용하기 쉽고, GraphQL은 요청을 줄일 수 있지만 쿼리별 비용 관리가 필요합니다. RPC는 내부 통신 효율과 스트리밍에 강점이 있지만, 분산 추적·헬스 체크·재시도 정책을 운영 체계에 포함해야 합니다.
13 | 상황별 선택 기준
외부 개발자에게 공개하는 API이거나 웹 표준 도구와의 호환성이 중요하다면 REST가 출발점으로 적합합니다. 모바일·웹·관리자 화면이 서로 다른 데이터를 요구하고 조회 조합이 복잡하다면 GraphQL을 검토할 수 있습니다.
여러 내부 서비스가 정해진 계약으로 빠르게 통신해야 하고, 언어별 클라이언트 생성과 스트리밍이 필요하다면 RPC 또는 gRPC가 적합할 수 있습니다. 하나의 시스템에서 REST와 GraphQL, RPC를 목적별로 함께 사용하는 것도 가능합니다.
☑ 체크리스트
- API의 주요 소비자가 외부 개발자인지 내부 서비스인지 정했는가?
- 리소스, 작업, 메시지 이름이 일관된 규칙을 따르는가?
- 인증·권한·입력 검증을 서버에서 처리하는가?
- 페이지네이션과 대량 데이터 조회 제한이 있는가?
- 오류 코드와 재시도 가능 여부를 구분했는가?
- 버전 변경과 하위 호환성 정책을 문서화했는가?
- 로그, 메트릭, 분산 추적을 통해 장애를 찾을 수 있는가?
📖 자주하는 질문 Q&A
REST와 REST API는 같은 뜻인가요?
엄밀히 말하면 REST는 아키텍처 스타일이고, REST API는 그 원칙을 적용해 만든 API를 뜻합니다. 실제 현장에서는 HTTP와 JSON을 사용하는 웹 API를 넓은 의미의 REST API라고 부르는 경우가 많습니다.
GraphQL이 REST보다 항상 좋은가요?
아닙니다. GraphQL은 클라이언트별 데이터 요구가 다양할 때 강점이 있지만, 쿼리 비용과 캐시 정책을 추가로 관리해야 합니다. 단순한 CRUD 서비스나 공개 API는 REST가 더 이해하기 쉬울 수 있습니다.
RPC는 내부 API에서만 사용해야 하나요?
반드시 내부 전용인 것은 아니지만, RPC는 서비스와 메서드 계약에 익숙한 환경에서 특히 편리합니다. 브라우저·외부 개발자·범용 HTTP 도구와의 호환성이 중요하면 REST 또는 별도 게이트웨이를 함께 고려해야 합니다.
세 방식을 한 서비스에서 함께 사용해도 되나요?
가능합니다. 예를 들어 외부 공개 API는 REST, 복잡한 웹 화면의 조회 계층은 GraphQL, 내부 마이크로서비스 통신은 gRPC로 나눌 수 있습니다. 다만 인증, 오류 형식, 추적 ID, 데이터 모델의 책임 범위는 전체 시스템에서 일관되게 관리해야 합니다.
📝 마무리
REST·GraphQL·RPC의 차이는 데이터를 리소스로 볼지, 필요한 필드로 조회할지, 원격 메서드 호출로 표현할지에 있습니다. 단순성과 범용성이 우선이면 REST, 복잡한 조회 요구가 핵심이면 GraphQL, 내부 서비스 간 명확한 계약과 효율이 중요하면 RPC를 우선 검토하면 됩니다.
최종 선택 전에는 통신 대상, 데이터 변경 방식, 성능 요구, 브라우저 호환성, 운영 도구까지 함께 평가해야 합니다.