쭈와

글

API Enum 설계 (안정성, 확장성, 호환성)

3월 13, 2026

Enum 구조를 API에 적용하면 정말 안전한 설계일까요? 당연히 그렇다고 생각 할 겁니다. 허용 가능한 값을 미리 정해두면 잘못된 데이터 입력을 막을 수 있고, 시스템이 예상치 못한 상황을 처리할 일도 줄어든다고 배웠으니까요. 그런데 실제로 서비스를 운영하면서 주문 상태 Enum을 확장해야 하는 상황을 겪고 나니, 생각이 완전히 바뀌었습니다. Enum은 분명 안정성을 높여주는 훌륭한 도구지만, 동시에 확장성을 제한하는 양날의 검이기도 합니다. Enum이 제공하는 데이터 안정성 API 설계에서 Enum 구조를 사용하면 데이터 입력 단계에서부터 오류를 차단할 수 있습니다. 상태(status), 유형(type), 역할(role) 같은 필드에 허용 가능한 값의 범위를 명확하게 정의해두면, 클라이언트가 엉뚱한 값을 보내는 상황 자체를 원천적으로 막을 수 있습니다. 예를 들어 주문 상태가 'pending', 'confirmed', 'shipped', 'delivered' 네 가지로 정해져 있다면, 'processing'이나 'complete' 같은 임의의 값이 들어올 일이 없습니다. 사례를 말씀드리면, 초기 설계 단계에서 주문 상태를 Enum으로 정의했을 때 QA 과정에서 발견되는 데이터 오류가 눈에 띄게 줄어들었습니다. 개발자들이 API 문서를 보고 정확히 어떤 값을 보내야 하는지 바로 알 수 있었고, 프론트엔드 팀에서도 드롭다운 메뉴 구현이 훨씬 명확해졌다는 피드백을 받았습니다. 이처럼 Enum은 시스템 전체의 데이터 일관성을 유지하는 데 분명한 장점이 있습니다. 명확한 의미 전달과 응답 해석 Enum 값은 특정 상태나 유형을 명확하게 표현할 수 있다는 점에서도 유용합니다. API 응답을 받은 클라이언트 입장에서는 각 값이 무엇을 의미하는지 직관적으로 이해할 수 있고, 이를 기반으로 UI 로직이나 비즈니스 로직을 구현하기가 쉬워집니다. 예를 들어 사용자 역할이 ...

자세한 내용 보기

API Null 처리 (데이터 명확성, 클라이언트 부담, 설계 전략)

3월 13, 2026

API를 처음 설계할 때 Null 값을 그냥 반환하면 되는 줄 알았습니다. 데이터가 없으면 Null을 보내면 되고, 클라이언트에서 알아서 처리하면 그만이라고 생각했습니다. 그러나 프로젝트에서 클라이언트 개발자들과 협업하면서 제 생각이 얼마나 단순했는지 깨닫게 됐습니다. Null 하나 때문에 클라이언트 코드가 복잡해지고, 예외 처리가 늘어나고, 심지어 앱이 크래시 나는 상황까지 발생했습니다. 이후 팀 내에서 Null 처리 정책을 정비하면서 이게 단순한 기술적 선택이 아니라 데이터 의미 전달과 사용성을 모두 고려해야 하는 설계 판단이라는 걸 배웠습니다. 데이터 명확성 API 응답에서 Null 값을 사용하는 가장 큰 이유는 데이터 상태를 명확하게 표현하기 위해서입니다. 예를 들어 사용자 프로필 API에서 전화번호 필드가 있다고 가정해보겠습니다. 이 필드가 응답에 아예 포함되지 않으면 클라이언트 입장에서는 "전화번호를 입력하지 않은 건가", "API 버전이 달라서 누락된 건가", "서버 오류로 빠진 건가" 판단하기 어렵습니다. 하지만 필드는 존재하되 값이 Null이면 "이 사용자는 전화번호를 등록하지 않았다"는 의미가 명확하게 전달됩니다. 사용자 프로필 API에서 일부 선택 항목들은 값이 없을 경우 필드 자체를 응답에서 제외했었는데, 이 방식이 클라이언트 개발자들에게 혼란을 줬습니다. 특히 조건부 렌더링을 구현할 때 필드 존재 여부를 먼저 확인하고, 값이 있는지 다시 확인하는 이중 체크가 필요했습니다. 이후 모든 필드를 항상 반환하고 값이 없으면 Null을 사용하는 방식으로 변경했더니 클라이언트 코드가 훨씬 단순해졌습니다. 스키마 정의(Schema Definition)도 명확해져서 API 문서 작성이 쉬워졌습니다. 여기서 스키마 정의란 API가 반환할 데이터 구조를 미리 정의해놓은 것으로, 클라이언트 개발자가 어떤 필드가 올지 예측할 수 있게 해주는 설계 명세입니다. 또한 응답 구조의...

자세한 내용 보기

API Boolean 필드 (상태 확장, 설계 판단, 구조 변경)

3월 12, 2026

API 설계할 때 Boolean 필드 하나 넣는 게 뭐가 어렵겠냐고 생각하셨나요? true와 false 두 개로 끝나니까 간단하고 명확하다고 생각했죠. 그런데 프로젝트를 진행하다 보면 이 단순함이 독이 될 때가 있습니다. 특히 서비스가 성장하면서 새로운 상태가 추가되어야 할 때, Boolean 구조로는 도저히 표현할 방법이 없어서 API 전체를 뜯어고쳐야 하는 상황이 생깁니다. 상태 확장 Boolean 필드의 가장 큰 문제는 딱 두 가지 상태만 표현할 수 있다는 점입니다. 활성(active)이냐 비활성이냐, 삭제됐느냐 안 됐느냐처럼 명확히 나뉘는 경우엔 완벽하게 작동합니다. 그런데 비즈니스 요구사항은 절대 그 자리에 가만히 있지 않습니다. 게시글 공개 여부를 관리하는 API를 만들 때 처음엔 public이라는 Boolean 필드 하나로 충분했습니다. 공개냐 비공개냐 두 가지만 있으면 됐으니까요. 그런데 몇 달 뒤 기획팀에서 예약 공개 기능을 요청했습니다. 특정 시간에 자동으로 공개되는 기능이었죠. 여기서 문제가 생겼습니다. 예약 상태를 Boolean으로 어떻게 표현할 수 있겠습니까? 어떤 분들은 Boolean 필드를 여러 개 만들면 되지 않냐고 하실 수 있습니다. public, scheduled, under_review 이런 식으로 필드를 계속 추가했죠. 그런데 이렇게 하면 상태 관리가 복잡해집니다. 한 게시글이 public=true, scheduled=true 이런 모순된 값을 가질 수도 있고, 클라이언트에서 여러 필드를 조합해서 판단해야 하니 오류가 생길 가능성이 커집니다( 출처: Martin Fowler ). 설계 판단 그렇다면 Boolean을 아예 쓰지 말아야 할까요? 그건 아닙니다. 핵심은 언제 Boolean을 쓰고 언제 다른 구조를 써야 하는지 판단하는 것입니다. 다음과 같은 기준으로 판단 할 수 있습니다. 앞으로도 상태가 두 가지로만 유지될 가능성이 높은가 이 필드가 다른 시스템 로직과 독립적으로 작동하는가 상태 변경 이...

자세한 내용 보기

API 네이밍 규칙 (일관성, 외부연동, 변환계층, 유지보수)

3월 12, 2026

여러 팀이 동시에 API를 개발하다 보면 어느 순간 데이터 필드 이름이 제각각이 되는 경우가 있습니다. 어떤 응답은 userName으로 오고, 다른 응답은 user_name으로 오는 식이죠. 클라이언트 개발자는 이 차이를 매번 확인하고 변환 로직을 추가해야 합니다. 저도 이런 상황을 겪으면서 API 필드 네이밍 규칙이 단순한 코딩 스타일 문제가 아니라는 점을 체감했습니다. 일관된 네이밍 규칙은 개발 생산성을 높이는 동시에 시스템 전체의 유지보수 비용을 줄이는 중요한 설계 요소입니다. 일관성 있는 데이터 구조가 만드는 차이 API 응답 구조에서 필드 네이밍 규칙이 통일되어 있으면 개발자는 새로운 엔드포인트를 처음 접할 때도 빠르게 이해할 수 있습니다. camelCase를 사용하는 서비스라면 모든 응답 필드가 firstName, userId, createdAt 같은 형식을 따르고, snake_case를 사용한다면 first_name, user_id, created_at 형태로 통일됩니다. 이런 일관성은 코드 작성 과정에서 예측 가능한 패턴을 제공하며, 개발자 경험(Developer Experience)을 크게 개선합니다. 제가 참여했던 한 프로젝트에서는 초기에 각 팀이 서로 다른 네이밍 스타일을 사용하면서 문제가 발생했습니다. 프론트엔드 개발자는 API 문서를 일일이 확인해야 했고, 데이터 매핑 과정에서 실수가 잦았습니다. 이후 팀 전체가 공통 네이밍 규칙을 정의하고 모든 신규 API에 적용하면서 이런 혼란이 크게 줄어들었습니다. 일관된 구조는 단순히 보기 좋은 것을 넘어서 실질적인 개발 효율을 높이는 요소였습니다. 특히 대규모 서비스에서는 수십 개의 마이크로서비스가 서로 데이터를 주고받는데, 각 서비스의 응답 형식이 다르면 통합 작업이 복잡해집니다. 네이밍 컨벤션(Naming Convention)은 이런 복잡도를 줄이는 첫 번째 방어선이 됩니다. 컨벤션이란 팀이나 조직에서 합의한 규칙을 의미하며, 이를 통해 코드 가독성과 유지보수성을 동시에 확보할 수 ...

자세한 내용 보기

API 연결 재사용 전략 (성능개선, 리소스관리, Keep-Alive)

3월 12, 2026

API 호출 시 매번 새로운 연결을 생성하면 평균 응답 시간이 수백 밀리초씩 늘어납니다. 솔직히 "연결 하나 만드는 게 뭐가 그리 오래 걸리겠어"라고 생각했는데, 실제 프로덕션 환경에서 측정해보니 생각보다 큰 차이가 났습니다. 특히 내부 서비스 간 통신이 빈번한 구조에서는 연결 생성 비용이 전체 성능에 직접적인 영향을 미칩니다. 그래서 많은 개발팀이 Connection Reuse 전략을 도입하는데, 문제는 이게 성능만 좋아지고 끝나는 게 아니라는 점입니다. 성능개선 효과는 확실합니다 네트워크 연결을 새로 만드는 과정에는 TCP 핸드셰이크라는 단계가 필요합니다. 클라이언트와 서버가 SYN, SYN-ACK, ACK 패킷을 주고받으며 연결을 수립하는 과정인데, 이게 보통 수십에서 수백 밀리초 정도 소요됩니다. HTTPS를 사용한다면 여기에 TLS 핸드셰이크 시간까지 추가됩니다. 매 요청마다 이 과정을 반복하면 당연히 전체 응답 시간이 느려질 수밖에 없습니다. HTTP Keep-Alive 방식의 Connection Reuse를 적용하면 이미 생성된 연결을 그대로 사용하기 때문에 핸드셰이크 과정을 건너뛸 수 있습니다. 필자가 운영했던 프로젝트에서는 이 방식을 도입한 후 평균 응답 시간이 약 30% 정도 단축됐습니다. 특히 짧은 간격으로 여러 번 API를 호출하는 구조에서는 효과가 더 두드러졌습니다. 연결 생성 오버헤드가 사라지니 네트워크 지연도 줄어들고, 전체적인 처리량(Throughput)도 개선됐습니다. 다만 이건 클라이언트 측면에서만 본 결과입니다. 서버 입장에서는 상황이 조금 다릅니다. 리소스관리 측면의 새로운 과제 연결을 재사용한다는 건 곧 연결을 오래 유지한다는 뜻입니다. 클라이언트 수가 적을 때는 문제가 안 되지만, 동시 접속자가 많아지면 서버가 관리해야 할 연결 수가 급격히 증가합니다. 각 연결마다 메모리와 파일 디스크립터 같은 시스템 자원이 할당되는데, 이게 쌓이면 서버 리소스가 빠르게 소진됩니다. 경험상 가장 골...

자세한 내용 보기

API Compression 전략 (네트워크, CPU, 선택 기준)

3월 12, 2026

필자가 예전에 운영하던 서비스에서 JSON 응답 크기가 생각보다 커서 모바일 사용자들이 응답 속도가 느리다는 피드백을 여러 차례 받았던 경험이 있습니다. 그때 처음으로 API Compression 전략을 본격적으로 검토하게 되었는데, 단순히 네트워크 절감만 생각했던 저에게 CPU 부하라는 또 다른 변수가 등장했기 때문입니다. 이 글에서는 제가 직접 겪은 API 압축 적용 과정과 그 과정에서 느낀 실제 효과, 그리고 어떤 기준으로 압축 전략을 선택해야 하는지 경험을 바탕으로 풀어보려 합니다. 네트워크 전송량 감소 API Compression은 서버와 클라이언트 사이에서 주고받는 데이터를 압축해 전달하는 방식입니다. 여기서 압축(Compression)이란 데이터 크기를 줄여서 전송 효율을 높이는 기술을 뜻하며, 주로 Gzip이나 Brotli 같은 알고리즘이 사용됩니다. 제가 처음 Gzip 압축을 적용했을 때는 응답 데이터 크기가 약 70% 가까이 줄어드는 걸 직접 확인했습니다. 특히 JSON 형식의 텍스트 데이터는 반복되는 구조가 많아서 압축 효과가 정말 컸습니다. 실제로 네트워크 대역폭 사용량이 줄어들면 응답 속도도 개선되는 경우가 많습니다. Wi-Fi 환경에서는 체감이 크지 않았지만, 3G나 LTE 환경에서는 확실히 달랐습니다. 사용자들이 "이전보다 빨라진 것 같다"는 피드백을 주기 시작했고, 모바일 환경에서 데이터 절감 효과가 크다는 걸 체감할 수 있었습니다. CPU 처리 비용 증가 하지만 압축을 적용하면서 예상치 못한 문제가 하나 발생했습니다. 서버 CPU 사용량이 눈에 띄게 증가한 것입니다. 데이터를 압축하고 해제하는 과정에서는 연산 작업이 필요하기 때문에, 서버와 클라이언트 모두 추가적인 처리 비용을 감수해야 합니다. 특히 트래픽이 몰리는 시간대에는 서버 부하(Load)가 평소보다 10~15% 정도 더 높아지는 현상을 관찰했습니다. 여기서 부하란 시스템이 처리해야 할 작업량을 의미하며, 부하가 높아지면 서버 응답 속도가 느...

자세한 내용 보기

API Partial Response (네트워크 절감, 구현 복잡성, 캐시 전략)

3월 12, 2026

사용자 프로필 API를 운영하던 중에 모바일 팀에서 "화면에 이름이랑 프로필 사진만 쓰는데 왜 이렇게 데이터가 많이 내려와요?"라는 질문을 받았던 적이 있습니다. 당시 API는 사용자 정보 전체를 한 번에 쏟아내고 있었죠. 그때 처음 고민하게 된 게 바로 API Partial Response 전략이었습니다. 필요한 데이터만 선택적으로 요청하고 받을 수 있다면 네트워크 부담을 확 줄일 수 있을 것 같았거든요. 그런데 막상 적용하려고 보니 생각보다 고려할 게 많더군요. 네트워크 절감 API Partial Response란 클라이언트가 필요한 데이터 필드만 지정해서 요청할 수 있도록 하는 설계 방식을 말합니다. 쉽게 말해 전체 메뉴판 중에서 먹고 싶은 것만 골라서 주문하는 것과 비슷하다고 보면 됩니다. 일반적인 API 구조에서는 정해진 응답 형식을 항상 동일하게 반환하는데, 이 방식은 클라이언트마다 필요한 정보가 다를 때 불필요한 데이터까지 함께 전송되는 문제가 생깁니다. 제가 직접 측정해봤을 때 프로필 API의 경우 전체 응답 크기가 약 15KB였는데, 이름과 프로필 이미지 URL만 요청하도록 바꾸니 2KB 정도로 줄어들었습니다. 특히 모바일 환경에서는 이런 차이가 체감 속도로 이어지더군요. 데이터 요금제를 쓰는 사용자 입장에서도 불필요한 데이터 소모가 줄어드는 효과가 있었습니다. 국내 주요 포털의 모바일 API 최적화 사례를 보면( 출처: 한국정보통신기술협회 ) 평균 30~40%의 트래픽 절감 효과를 보고하고 있습니다. 솔직히 처음에는 "이 정도 차이가 큰 의미가 있을까?" 싶었는데, 실제 서비스 환경에서 하루 수백만 건의 API 호출이 발생하는 상황이라면 이야기가 달라집니다. 누적 트래픽 비용 측면에서도 무시할 수 없는 규모가 되더군요. 구현 복잡성 네트워크 효율은 좋았지만 서버 개발자 입장에서는 머리가 아파지기 시작했습니다. 기존에는 정해진 구조만 반환하면 됐는데, 이제는 요청마다 다른 필드 조합을 처리해...

자세한 내용 보기