2025년 9월 02일·7분
API에서의 Protobuf vs JSON: 속도, 용량, 호환성
API에서 Protobuf와 JSON을 비교: 페이로드 크기, 속도, 가독성, 툴링, 버전 관리, 실제 제품에서 각 형식이 적합한 상황을 정리합니다.
API에서 Protobuf와 JSON을 비교: 페이로드 크기, 속도, 가독성, 툴링, 버전 관리, 실제 제품에서 각 형식이 적합한 상황을 정리합니다.
API가 데이터를 주고받을 때는 데이터 형식이 필요합니다—요청과 응답 본문에서 정보를 표준화된 방식으로 표현하는 방법입니다. 그 형식은 네트워크로 전송하기 위해 직렬화(바이트로 변환)되고, 클라이언트와 서버에서 다시 사용 가능한 객체로 역직렬화됩니다.
가장 흔한 선택지 두 가지는 JSON과 **Protocol Buffers(Protobuf)**입니다. 둘 다 동일한 비즈니스 데이터(사용자, 주문, 타임스탬프, 아이템 목록)를 표현할 수 있지만, 성능, 페이로드 크기, 개발자 워크플로우에서 서로 다른 절충을 합니다.
**JSON (JavaScript Object Notation)**은 객체와 배열 같은 단순한 구조로 구성된 텍스트 기반 형식입니다. REST API에서 인기가 높은 이유는 읽기 쉽고 로그로 남기기 편하며 curl이나 브라우저 DevTools 같은 도구로 쉽게 검사할 수 있기 때문입니다.
대부분의 언어가 JSON을 잘 지원하고, 응답을 보면 바로 내용을 이해할 수 있다는 점이 보편화의 큰 이유입니다.
Protobuf는 Google이 만든 바이너리 직렬화 형식입니다. 텍스트를 보내는 대신 .proto 파일로 정의한 스키마에 따라 컴팩트한 바이너리 표현을 전송합니다. 스키마는 필드, 타입, 숫자 태그를 설명합니다.
바이너리이고 스키마 기반이기 때문에 Protobuf는 보통 페이로드가 작고, 파싱이 빠른 편입니다—트래픽이 많거나 모바일 네트워크, 지연 민감 서비스에서 중요한 장점입니다(주로 gRPC 환경에서 많이 쓰이지만 그에 한정되지는 않습니다).
무엇을 보내는지와 어떻게 인코딩하는지를 분리해서 생각하는 게 중요합니다. id, name, email을 가진 "user"는 JSON과 Protobuf 모두에서 모델링할 수 있습니다. 차이는 지불해야 하는 비용입니다:
정답은 없습니다. 많은 공개 API는 접근성 및 유연성 때문에 JSON을 기본으로 사용합니다. 내부 서비스 간 통신, 성능 민감 시스템, 엄격한 계약이 필요한 경우 Protobuf가 더 적합할 수 있습니다. 이 가이드는 이념이 아닌 제약에 따라 선택하도록 돕는 것을 목표로 합니다.
API가 데이터를 반환할 때 "객체"를 네트워크로 그대로 전송할 수는 없습니다. 먼저 그것을 바이트 스트림으로 바꿔야 합니다. 이 변환이 직렬화입니다—데이터를 운송 가능한 형태로 포장하는 것으로 생각하세요. 반대편 클라이언트는 이 바이트를 다시 객체로 푸는(역직렬화) 작업을 합니다.
일반적인 요청/응답 흐름은 다음과 같습니다:
이 "인코딩 단계"가 포맷 선택이 중요한 지점입니다. JSON 인코딩은 {"id":123,"name":"Ava"} 같은 읽을 수 있는 텍스트를 만듭니다. Protobuf 인코딩은 도구 없이는 사람이 이해하기 어려운 컴팩트한 바이너리를 생성합니다.
모든 응답은 반드시 포장되고 풀려야 하므로, 형식은 다음에 영향을 미칩니다:
API 스타일은 종종 의사결정에 영향을 줍니다:
curl로 테스트하기 쉽고 로그·검사에 용이해 JSON을 쓰는 경향이 있습니다.JSON을 gRPC에서 사용(트랜스코딩을 통해)할 수도 있고 Protobuf를 일반 HTTP로 사용할 수도 있지만, 스택의 기본적인 사용성(프레임워크, 게이트웨이, 클라이언트 라이브러리, 디버깅 습관)이 일상 운영에서 무엇이 더 쉬운지를 자주 결정합니다.
사람들이 protobuf vs json을 비교할 때 보통 두 가지 지표로 시작합니다: 페이로드 크기와 인코드/디코드에 걸리는 시간. 핵심은 단순합니다: JSON은 텍스트라 일반적으로 장황하고, Protobuf는 바이너리라 컴팩트합니다.
JSON은 필드 이름을 반복하고 숫자, 불리언, 구조를 텍스트로 표현하므로 전송 바이트 수가 늘어나는 경향이 있습니다. Protobuf는 필드 이름 대신 숫자 태그를 사용하고 값을 효율적으로 패킹하므로 특히 큰 객체, 반복 필드, 깊게 중첩된 데이터에서 눈에 띄게 작아지는 경우가 많습니다.
다만 압축은 격차를 좁힐 수 있습니다. gzip이나 brotli를 사용하면 JSON의 반복 키가 매우 잘 압축되므로 "JSON vs Protobuf 크기" 차이는 실제 배포에서 줄어들 수 있습니다. Protobuf도 압축할 수 있지만 상대적 이점은 상황에 따라 작아집니다.
JSON 파서는 텍스트를 토큰화하고 검증하며, 문자열을 숫자로 변환하고 이스케이프/유니코드 처리 같은 엣지 케이스를 다뤄야 합니다. Protobuf 디코딩은 더 직접적입니다: 태그를 읽고 타입에 맞춰 값을 읽습니다. 많은 서비스에서 Protobuf는 CPU 시간과 가비지 생성량을 줄여 부하 하에서 꼬리 지연(p99 등)을 개선할 수 있습니다.
모바일 네트워크나 높은 레이턴시 링크에서는 바이트 수가 적을수록 전송이 빠르고 라디오 사용 시간이 줄어 배터리에도 도움이 됩니다. 다만 응답이 이미 작다면 핸드셰이크 오버헤드, TLS, 서버 처리 시간이 지배적일 수 있어 형식 선택의 효과가 덜 보일 수 있습니다.
실제 페이로드로 측정하세요:
이렇게 하면 "API 직렬화" 논쟁을 당신의 API에 맞는 데이터로 바꿀 수 있습니다.
개발자 경험은 JSON이 기본적으로 우위에 있는 영역입니다. JSON 요청/응답은 거의 어디서나 검사할 수 있습니다: 브라우저 DevTools, curl 출력, Postman, 리버스 프록시, 텍스트 로그 등. 문제가 생기면 "우리가 실제로 보낸 것이 무엇인가"를 복사/붙여넣기만 하면 재현이 쉽습니다.
Protobuf는 다릅니다: 컴팩트하고 엄격하지만 사람이 읽을 수 없습니다. 바이너리 Protobuf를 그대로 로그하면 base64 블롭이나 읽을 수 없는 이진이 보입니다. 페이로드를 이해하려면 올바른 .proto 스키마와 디코더(예: protoc, 언어별 툴링, 혹은 서비스의 생성된 타입)가 필요합니다.
JSON으로는 문제 재현이 직관적입니다: 로그된 페이로드를 가져와 민감정보를 가리고 curl로 재생하면 거의 최소한의 테스트 케이스가 됩니다.
Protobuf에서는 보통 이렇게 디버깅합니다:
이 추가 단계는 팀이 반복 가능한 워크플로우를 갖추고 있다면 관리 가능합니다.
구조화된 로깅은 두 형식 모두에 도움이 됩니다. 요청 ID, 메서드 이름, 사용자/계정 식별자, 주요 필드를 로깅하고 전체 바디 대신 핵심 정보를 남기세요.
Protobuf 전용 팁:
.proto를 썼나" 혼란을 줄이세요.JSON의 경우 차이를 쉽게 보기 위해 정규화된(canonicalized) JSON(안정적인 키 순서)을 로깅하는 것을 고려하세요.
API는 단순히 데이터를 옮기는 것이 아니라 의미를 전달합니다. JSON과 Protobuf의 가장 큰 차이는 그 의미가 얼마나 명확하고 엄격하게 정의되는가입니다.
JSON은 기본적으로 "스키마 없음"입니다: 어떤 필드든 보낼 수 있고, 많은 클라이언트는 그것이 그럴듯해 보이기만 하면 받아들입니다.
이 유연성은 초기에는 편리하지만 문제를 숨길 수 있습니다. 흔한 함정은:
userId, 다른 응답에서는 user_id 또는 코드 경로에 따라 필드가 누락됨"42", "true", "2025-12-23" 같은 문자열로 보내는 관행null이 "알 수 없음", "설정되지 않음", "의도적으로 비어 있음" 중 무엇을 의미하는지 모호함JSON Schema나 OpenAPI 명세로 보완할 수 있지만, JSON 자체는 소비자가 이를 따르도록 강제하지 않습니다.
Protobuf는 .proto 파일로 스키마를 요구합니다. 스키마는 공유 계약으로 다음을 명시합니다:
그 계약은 실수(예: 정수를 문자열로 바꾸는 등)를 방지하는 데 도움이 됩니다—생성된 코드는 특정 타입을 기대합니다.
Protobuf에서는 숫자는 숫자, 열거형은 허용된 값으로 제한, 타임스탬프는 well-known 타입을 쓰는 것이 일반적입니다(임의의 문자열 포맷 대신). 또한 proto3에서는 optional 필드나 래퍼 타입을 사용하면 "설정되지 않음"과 기본값을 구분할 수 있어 부재의 의미가 더 명확합니다.
정확한 타입과 예측 가능한 파싱이 여러 팀과 언어에 걸쳐 중요하다면 Protobuf가 제공하는 안전장치가 큰 도움이 됩니다.
API는 진화합니다: 필드를 추가하고 동작을 조정하며 오래된 부분을 폐기합니다. 목표는 소비자를 놀라게 하지 않고 계약을 변경하는 것입니다.
좋은 진화 전략은 둘 다를 목표로 하지만, 최소한 백워드 호환을 지키는 것이 보통의 기준입니다.
Protobuf에서는 각 필드에 번호(예: email = 3)가 있습니다. 그 번호가 와이어상에서의 정체성입니다. 이름은 주로 사람과 생성 코드용입니다.
그 때문에:
안전한 변경(보통)
위험한 변경(종종 깨뜨림)
권장 관행: 이전 번호/이름은 reserved로 표시하고 변경 로그를 유지하세요.
JSON은 내재적 스키마가 없으므로 호환성은 팀의 패턴에 달려 있습니다:
필드가 사용 중단될 때는 시기를 문서화하세요: 언제까지 지원하는지, 대체 필드는 무엇인지. 단순한 버전 정책(예: "추가적 변경은 비파괴적; 제거는 새 메이저 버전 필요")을 발표하고 지키는 것이 도움이 됩니다.
JSON과 Protobuf 사이 선택은 종종 API가 어디에서 실행되어야 하는지, 팀이 무엇을 유지보수할지에 달려 있습니다.
JSON은 사실상 보편적입니다: 모든 브라우저와 백엔드 런타임이 추가 의존성 없이 파싱할 수 있습니다. 웹에서는 fetch() + JSON.parse()가 자연스러운 경로이고 프록시, API 게이트웨이, 관찰 도구들이 기본적으로 JSON을 "이해"합니다.
브라우저에서도 Protobuf를 쓸 수 있지만 여분의 비용이 듭니다. 보통 Protobuf 라이브러리(또는 생성된 JS/TS 코드)를 추가하고 번들 크기를 관리해야 하며, 브라우저 툴링으로 쉽게 검사 가능한 HTTP 엔드포인트인지 결정해야 합니다.
iOS/Android 및 백엔드 언어(Go, Java, Kotlin, C#, Python 등)에서 Protobuf 지원은 성숙해 있습니다. Protobuf는 보통 플랫폼별 라이브러리를 사용하고 .proto에서 코드를 생성하는 것을 전제로 합니다.
코드 생성의 장점:
단점:
.proto 패키지 배포, 버전 고정)Protobuf는 gRPC와 밀접하게 연계되어 완전한 툴링 스토리를 제공합니다: 서비스 정의, 클라이언트 스텁, 스트리밍, 인터셉터 등. gRPC를 고려 중이라면 Protobuf가 자연스러운 선택입니다.
전통적인 JSON REST API를 구축 중이라면 JSON의 툴링(브라우저 DevTools, curl 친화적 디버깅, 일반 게이트웨이)이 더 단순하게 느껴지는 경우가 많습니다—특히 공개 API와 빠른 통합이 필요한 상황에서 그렇습니다.
아직 API 표면을 탐색 중이라면 두 스타일을 빠르게 프로토타입해 보는 것이 좋습니다. 예를 들어 많은 팀은 Koder.ai 같은 플랫폼을 사용해 공개 호환성을 위해 JSON REST API를 빠르게 띄우고 내부적으로는 gRPC/Protobuf 서비스를 만들어 효율성을 검증한 뒤 실제 페이로드로 벤치마크하여 기본값을 결정합니다. Koder.ai는 전체 스택 앱(웹의 React, 백엔드의 Go + PostgreSQL, 모바일의 Flutter)을 생성하고 플래닝 모드, 스냅샷/롤백을 지원하므로 계약을 반복하기에 비용이 적습니다.
JSON과 Protobuf 선택은 페이로드 크기나 속도뿐 아니라 캐싱 레이어, 게이트웨이, 팀이 사고 대응 시 사용하는 도구와의 적합성에도 영향을 줍니다.
대부분의 HTTP 캐싱 인프라(브라우저 캐시, 리버스 프록시, CDN)는 특정 바디 형식이 아닌 HTTP 의미론에 최적화되어 있습니다. CDN은 응답이 캐시 가능하면 어떤 바이트든 캐시할 수 있습니다.
다만 많은 팀이 엣지에서 HTTP/JSON을 기대하는데, 그 이유는 검사와 문제 해결이 쉽기 때문입니다. Protobuf도 캐싱은 동작하지만 다음을 신경 써야 합니다:
Vary)Cache-Control, ETag, Last-Modified)Content-Type과 Accept)둘 다 지원하려면 콘텐츠 네고시에이션을 사용하세요:
Accept: application/json 또는 Accept: application/x-protobuf 전송Content-Type으로 응답캐시가 이를 알게 하려면 Vary: Accept를 설정하세요. 그렇지 않으면 캐시가 JSON 응답을 저장했다가 Protobuf 클라이언트에게 반환하는 실수를 할 수 있습니다.
API 게이트웨이, WAF, 요청/응답 변환기, 관찰성 도구는 종종 JSON 바디를 전제로 합니다:
바이너리 Protobuf는 툴이 Protobuf를 인식하지 않으면 이런 기능들을 제한할 수 있습니다(혹은 디코딩 스텝을 추가해야 함).
흔한 패턴은 엣지에는 JSON, 내부에는 Protobuf입니다:
이렇게 하면 외부 통합을 단순하게 유지하면서 양쪽의 장점을 모두 활용할 수 있습니다.
JSON을 쓰든 Protobuf를 쓰든 형식 선택은 인코딩·파싱 방식에 영향을 줄 뿐, 인증·암호화·인가·서버 측 검증 같은 핵심 보안 요건을 대체하지 않습니다. 빠른 직렬화 라이브러리가 있다고 해도 신뢰할 수 없는 입력을 제한하지 않으면 API 자체가 안전해지지 않습니다.
Protobuf가 바이너리라서 더 "안전"하다고 생각하기 쉽지만, 이는 보안 전략이 아닙니다. 공격자는 사람이 읽을 수 있는지 여부와 상관없이 엔드포인트를 노립니다. API가 민감 필드를 누출하거나 잘못된 입력을 허용하면 형식 전환으로 해결되지 않습니다.
전송은 TLS로 암호화하고, 권한 검사를 시행하며, 입력을 서버에서 검증하고, 로깅을 안전하게 처리하세요.
두 형식이 공유하는 위험:
부하와 남용에서 API를 지키려면 두 형식 모두에 다음과 같은 보호막을 적용하세요:
요약: "바이너리 대 텍스트" 차이는 주로 성능과 사용성에 영향을 줍니다. 보안과 신뢰성은 일관된 한도 설정, 최신 라이브러리 유지, 명시적 검증에서 나옵니다.
JSON과 Protobuf의 우열을 따지기보다, API가 무엇을 최적화해야 하는지(사람 친화성·도달 범위 또는 효율성·엄격한 계약)에 따라 결정하세요.
JSON은 호환성과 빠른 문제 해결이 필요할 때 보통 안전한 기본입니다.
전형적 시나리오:
curl 테스트)Protobuf는 사람이 읽기 쉬운지보다 성능과 일관성이 중요한 경우에 유리합니다.
전형적 시나리오:
다음 질문들로 선택을 좁혀보세요:
아직 결정을 못했다면 "엣지엔 JSON, 내부엔 Protobuf" 접근법이 현실적인 타협입니다.
형식 마이그레이션은 모든 것을 다시 쓰는 것이 아니라 소비자 위험을 줄이는 과정입니다. 안전한 전환은 마이그레이션 기간 동안 API가 계속 사용 가능하도록 하고 롤백을 쉽게 합니다.
리스크가 낮은 영역(보통 내부 서비스 호출이나 단일 읽기 전용 엔드포인트)을 골라 시작하세요. 스키마, 생성된 클라이언트, 관찰성 변화를 검증할 수 있습니다.
실용적인 첫걸음은 기존 리소스에 대한 Protobuf 표현을 추가하되 JSON 형태는 그대로 유지하는 것입니다. 이렇게 하면 스키마에서 모호한 부분(누락 vs 빈값, 숫자 vs 문자열, 날짜 포맷)을 발견하고 해결할 수 있습니다.
외부 API의 경우 이중 지원이 가장 부드러운 경로입니다:
Content-Type과 Accept 헤더로 형식을 협상/v2/...) 제공이 기간 동안 두 형식을 같은 소스 오브 트루스에서 생성해 미묘한 드리프트를 방지하세요.
다음 항목을 계획하세요:
.proto 파일, 필드 주석, 구체적인 요청/응답 예제(JSON/Protobuf 모두)를 공개해 소비자가 올바르게 해석할 수 있도록 하세요. 짧은 마이그레이션 가이드와 변경 로그는 지원 부담을 줄이고 도입 시간을 단축합니다.
JSON과 Protobuf 선택은 이념보다 트래픽, 클라이언트, 운영 제약의 현실에 더 좌우됩니다. 가장 신뢰할 수 있는 경로는 측정하고 문서화하며 API 변경을 지루하게 만드는 것입니다.
대표 엔드포인트에 작은 실험을 수행하세요.
추적 항목:
스테이징에서 프로덕션과 유사한 데이터로 수행한 뒤 프로덕션의 작은 트래픽 슬라이스에서 검증하세요.
JSON Schema/OpenAPI나 .proto 파일 중 무엇을 쓰든:
Protobuf를 선택해도 문서는 친절하게 유지하세요:
문서나 SDK 가이드를 유지한다면 관련 링크를 명확히 하세요(예: /docs 및 /blog). 가격·사용 한도 등이 형식 선택에 영향을 준다면 그것도 명시하세요(/pricing).
JSON은 읽기 쉽고 로그에 남기기 편하며 일반 도구로 테스트하기 쉬운 텍스트 기반 형식입니다. Protobuf는 .proto 스키마로 정의되는 컴팩트한 바이너리 형식으로, 종종 더 작은 페이로드와 더 빠른 파싱을 제공합니다.
선택은 제약에 따라 달라집니다: 도달 범위와 디버깅 용이성(=JSON) 대 효율성과 엄격한 계약(=Protobuf).
API는 바이트를 전송합니다; 메모리 내 객체를 그대로 보낼 수는 없습니다. **직렬화(Serialization)**는 서버 객체를 전송 가능한 페이로드(JSON 텍스트 또는 Protobuf 바이너리)로 인코딩하는 과정이고, **역직렬화(Deserialization)**는 그 바이트를 다시 객체로 디코딩하는 과정입니다.
포맷 선택은 대역폭, 지연 시간, 인코딩/디코딩에 소비되는 CPU에 영향을 줍니다.
보통 그렇습니다. 특히 큰 객체나 중첩 구조, 반복 필드가 많을 때 Protobuf는 필드명을 숫자 태그로 대체하고 효율적으로 인코딩하므로 더 작아집니다.
다만 gzip/brotli 같은 압축을 사용하면 JSON의 반복 키가 매우 잘 압축되어 실제 환경에서 크기 차이가 줄어들 수 있습니다. 원시(raw) 크기와 압축된 크기 둘 다 측정하세요.
그럴 수 있습니다. JSON 파서는 텍스트 토큰화, 이스케이프/유니코드 처리, 문자열→숫자 변환을 수행해야 합니다. Protobuf 디코딩은 태그를 읽고 타입에 맞춰 값을 읽는 식으로 더 직접적입니다. 그 때문에 CPU 시간과 할당이 줄어들어 때로는 지연 시간이 개선됩니다.
다만 페이로드가 아주 작다면 TLS, 네트워크 RTT, 애플리케이션 처리 시간이 직렬화 비용보다 더 크게 작용할 수 있습니다.
기본적으로 어렵습니다. JSON은 사람이 읽을 수 있어 DevTools, 로그, curl, Postman 등에서 바로 확인할 수 있습니다. Protobuf는 바이너리이므로 원시 바이트를 로그하면 base64나 읽을 수 없는 바이너리로 보입니다. 올바른 .proto 스키마와 디코더가 있어야 내용을 이해할 수 있습니다.
개선 팁: 디코딩된(그리고 민감정보는 마스킹된) '디버그 뷰'(보통 JSON)를 바이너리 페이로드와 함께 로그에 남기세요.
JSON은 기본적으로 스키마가 없어서 자유로운 구조를 허용합니다(필요하면 JSON Schema/OpenAPI로 보강 가능). 이 유연성은 초기에 편리하지만 다음과 같은 문제를 숨길 수 있습니다: 일관성 없는 필드 이름, 숫자/불린/날짜가 문자열로 전송되는 'stringly-typed' 관행, null의 모호성 등.
Protobuf는 .proto 파일로 타입과 필드를 명시해 강한 계약을 제공합니다. 생성된 코드는 타입을 기대하므로 실수(예: 정수를 문자열로 바꿈)를 방지하는 데 도움이 됩니다.
Protobuf에서는 각 필드에 숫자 태그가 할당됩니다(예: email = 3). 그 숫자가 실제 전송 상의 정체성입니다. 안전한 변경 방법은 보통 다음과 같습니다:
reserved로 표시위험한 변경: 필드 번호 재사용, 타입을 호환 불가능하게 변경, 삭제 후 번호 재사용 등은 클라이언트 호환성을 깨뜨립니다.
JSON은 스키마가 내재되어 있지 않아 관례와 규율에 의존합니다. 보통은 additive 변경(새 필드 추가)을 선호하고, 타입 변경 시 새 필드 이름을 도입합니다.
예, 가능합니다. HTTP 콘텐츠 네고시에이션을 사용하세요:
Accept: application/json 또는 Accept: application/x-protobuf를 보냅니다Content-Type으로 응답합니다Vary: Accept 헤더를 설정하세요도구 제약으로 네고시에이션이 어렵다면 별도의 엔드포인트(예: )를 임시로 제공하는 것도 마이그레이션 전략입니다.
환경에 따라 다릅니다:
Protobuf를 선택하면 코드 생성/버전 관리 비용을 고려해야 합니다.
형식 선택 자체가 보안이나 신뢰성의 전부는 아닙니다. Protobuf가 바이너리라고 해서 안전한 건 아닙니다. 공격자는 사람이 읽을 수 있는지 여부와 상관없이 취약점을 악용할 수 있습니다.
공통 권장사항:
파서 취약점에는 사용 중인 라이브러리를 최신으로 유지하는 것이 중요합니다.
/v2/...