API Design on C++

TL;DR

• API는 구현이 아니라 사용자와의 계약(contract) 이다

• 좋은 API는 존재감이 없고, 나쁜 API는 지속적인 고통을 준다

• Top-down(사용자 중심) 설계가 거의 항상 정답이다

• API는 성공할수록 변경 비용이 기하급수적으로 증가한다

• 구현 디테일이 API로 새는 순간, 미래의 선택지는 사라진다

---

개요 (Overview)

이 강연은 “API를 어떻게 설계해야 하는가?”라는 질문을
문법이나 스타일이 아닌 현실적인 유지보수 관점에서 다룬다.

핵심 메시지는 단 하나다.

API 설계의 출발점은
‘멋진 구현’이 아니라 ‘사용자가 실제로 어떻게 사용할 것인가’다.

강연은 다음 질문들에 답한다.

• 좋은 API와 나쁜 API의 차이는 무엇인가?

• 왜 사용자 관점(top-down)이 중요한가?

• API가 커질수록 왜 변경하기 어려워지는가?

• API/ABI 호환성은 설계에 어떤 제약을 주는가?

• 실무에서 API를 평가할 때 무엇을 봐야 하는가?

---

상세 설명 (Detailed Breakdown)

1. 좋은 API와 나쁜 API

좋은 API의 특징

• 사용자가 API의 존재를 의식하지 않는다

• 도메인 지식만으로 직관적인 사용이 가능하다

• 수년에서 수십 년까지 사용 가능하다

• 변경이 적고, 변경되더라도 사용자에게 주는 충격이 작다

• 테스트, 성능, 확장성에 긍정적으로 기여한다

좋은 API는 “좋다”는 느낌조차 들지 않는다

---

나쁜 API의 특징

• 플랫폼 또는 구현 디테일이 그대로 노출된다

• 사용할 때마다 문서를 확인해야 한다

• 오용(misuse)하기 쉽다

• 테스트가 어렵고 버그가 자주 발생한다

• deprecate → 새 API → 또 deprecate의 반복

나쁜 API는 한 번 쓰고 끝나는 것이 아니라 지속적인 고통을 준다

---

2. API 설계 철학: Top-down vs Bottom-up

Top-down 설계 (권장)

1. 사용자 사용 시나리오를 먼저 정의한다

2. 예제 코드와 문서를 먼저 작성한다

3. API를 정의한다

4. 마지막에 구현한다

→ API가 구현의 언어가 아니라 사용자의 언어로 말하게 된다

---

Bottom-up 설계 (위험)

• 구현(알고리즘, 외부 라이브러리)부터 시작한다

• API가 구현에 끌려다닌다

문제점:

• 구현 디테일이 API로 그대로 새어나온다

• 사용자가 내부 구현을 알아야만 사용 가능하다

• 테스트, 확장, 교체가 모두 어려워진다

---

3. API 사용자 규모와 변경 비용

사용자 규모	API 변경 난이도
개인 / 소규모	낮음
사내 다수 팀	높음 (대량 수정, 리빌드 필요)
공개 API	거의 불가능

API는 성공할수록 고치기 어려워진다

---

API / ABI 호환성

용어 정리 (Terminology)

• Library API + Compiler ABI = Library ABI

ABI 호환성

• ABI 호환성 깨짐은

  • 최악의 경우: 미묘한 오동작

  • 차선의 경우: 즉시 크래시

• 동적 링크 라이브러리 사용 시 특히 중요 (예: libstdc++)

• 모든 사용자가 항상 전체를 다시 컴파일한다면 무시할 수도 있음

API 호환성

• API 비호환은 보통 컴파일 자체가 되지 않음

• 라이브러리를 배포할 때 (바이너리/소스 모두)

• 전체를 다시 컴파일하는 경우에도 중요

---

ABI 호환 가능한 변경

• 새로운 free function 추가

• 클래스에 friend 선언 추가/제거

• enum 끝에 값 추가 (단, enum 타입 크기가 바뀌지 않는 경우)

• static 멤버 변수/함수 추가

• non-virtual 메서드 추가 (오버로드 제외)

• 생성자 추가

• 기본 인자 값 변경

• private non-virtual 메서드 제거

• typedef 및 새 타입 추가

• inline 함수 → non-inline 함수로 변경

  • 기존에 컴파일된 코드는 이전 구현을 계속 사용

---

ABI 호환 불가능한 변경

• 메서드 변경
  (const/constexpr, 반환 타입, 인자 위치, cv-qualifier, 템플릿 파라미터, final/override, noexcept, inline/템플릿 구현 내용 등)

• 클래스 상속 구조 변경

• 클래스 멤버 추가/제거/순서 변경/타입 변경

• 오버로드 추가 또는 제거

• 멤버 함수 인라이닝 방식 변경

• 접근 제어자 변경

• virtual 함수 추가/제거/순서 변경
  (non-virtual ↔ virtual 변경 포함)

• 던지는 예외 및 예외 계층 변경

• 전역 데이터의 타입 또는 cv-qualifier 변경

---

API 호환 가능한 변경

• 기본값을 가진 파라미터 추가

• 클래스에 메서드 추가

• 클래스에 멤버 추가

• 클래스 추가

• 멤버 또는 메서드 순서 변경

---

API 호환 불가능한 변경

• 인자, public/protected 메서드, 멤버, 클래스 제거

• 인자 또는 멤버 변수 타입 변경

• public/protected 멤버나 메서드 이름 변경

• 클래스를 다른 헤더로 이동

---

API 설계 원칙 (Guiding Principles)

1. 사용하기 쉬워야 한다

• 온보딩 시간이 짧아진다

• 버그와 오용이 줄어든다

• 사용률이 증가한다

• 최소 놀람의 원칙(Principle of Least Surprise)

방법:

• 클래스, 메서드, 파라미터, 타입 이름을 잘 짓는다

  • 의미가 명확하고

  • 간결하며

  • 도메인 의미를 반영하고

  • 일반적으로 통용되는 용어를 사용

• 컴포넌트 내부/외부에서 일관성 유지

• 적절한 추상화 수준 유지

• 예: 컨테이너 자체 대신 iterator를 전달

---

2. 오용하기 어렵게 설계하라

• 계약이 명확하고 범위가 좁아야 한다

• 일반적으로 받아들여진 코딩 관례를 따른다

• 사용자가 예상하는 대로 정확히 동작해야 한다

---

3. 문서화가 되어 있어야 한다

문서가 없으면, 존재하지 않는 것이다

• 공개된 모든 요소를 문서화한다

• 계약 정의는 명확하고, 간결하며, 모호하지 않아야 한다

• 튜토리얼 제공 (문서도 코드다)

• 문서 스타일 가이드를 유지한다

---

4. 최소한으로 완결되어야 한다 (Minimally Complete)

• 필요한 것만 포함한다

• API 조합으로 충분히 만들 수 있는 기능은 제외한다

• 추상화와 표현 불변성을 유지한다

  • 추상화: 구현이 달라도 동작은 구분되지 않아야 함

  • 표현 불변성: 객체가 항상 만족해야 하는 조건

예시:

• std::mutex + std::lock_guard

  • mutex는 primitive 제공

  • lock_guard는 예외 안전한 RAII 유틸리티 제공

---

5. 느슨하게 결합하라 (Loosely Coupled)

• 컴포넌트 간 상호 의존을 최소화한다

• 컴포넌트는 응집력 있게 구성한다

권장 사항:

• 순환 의존성 피하기

• 필요한 것만 include/import

• callback, observer 패턴 활용

• Mediator 패턴 활용 (자원 접근 단일 창구)

---

6. 구현 디테일을 노출하지 마라

Hyrum’s Law:

“인터페이스의 모든 관측 가능한 속성은
언젠가 누군가에 의해 의존된다”

효과:

• 사용자는 도메인 관점으로 설계 가능

• API 제공자는 변경 자유도가 커진다

• 업그레이드와 테스트가 쉬워진다

가이드라인:

• 도메인 타입을 공개 인터페이스에 사용

• 내부 타입 노출 금지

• 의존 라이브러리 타입/함수 노출 금지

---

7. 장기 사용을 고려하라

• 요구사항은 변한다

• 플랫폼 제약도 변한다

• 처음부터 모든 기능을 넣을 필요는 없다

• 기능은 점진적으로 추가 가능해야 한다

예시:

• in/out 파라미터를 struct/class로 정의
  → 이후 필드 확장 가능

최소 놀람의 원칙:

• 사용자의 예측이 맞아야 한다

• 도메인 기반 추측이 틀리면 실패한 API다

---

8. 보일러플레이트 코드를 피하라

• 특정 작업을 수행하는 데 필요한 코드 양이
  API 적합성을 판단하는 좋은 지표다

• 적절한 추상화 수준 유지

  • 웹 서버 API는 socket이 아니라 HTTP 요청/헤더를 다뤄야 한다

• 반복되는 공통 작업을 위한 유틸리티 제공

• 테스트 작성이 쉬워진다

---

9. 플랫폼 독립적으로 설계하라

• 특정 OS에서만 동작하는 설계 금지

• 특정 OS에서만 동작하지 않는 설계도 금지

  • Windows vs POSIX

  • 엔디안 문제

  • 컴파일러 종속 이슈

• 오버로드되는 함수와 동일한 타입 사용

---

10. 테스트 드라이버를 고려해 설계하라

API 설계의 황금률:

네 API를 사용하는 테스트를 직접 작성해봐라

• 애플리케이션 테스트/통합 테스트에서 사용 가능해야 한다

• mock 불가능한 concrete class API는 피한다

• 인터페이스 기반 설계 권장

• 복잡한 API는 mock 범위를 최소화

  • 인터페이스 분리 원칙(ISP)

• 의존성을 끊고 단독 실행 가능해야 한다

---

11. 테스트 가능하게 설계하라

• 내부 기능을 테스트할 수 있도록 API를 설계한다

• 시스템/라이브러리 의존성을 대체할 수 있어야 한다

권장 기법:

• PIMPL (Pointer to Implementation) 패턴

---

요약 (Summary)

• 좋은 API를 작성하는 것은 매우 중요하다

• 실제 사용 방식을 반드시 고려해야 한다

• API 설계 원칙을 적용하면 품질이 크게 향상된다

---

핵심 정리 (Takeaways)

• API는 코드가 아니라 약속이다

• 사용자 관점 없이 좋은 API는 나올 수 없다

• 구현 디테일은 절대 API로 새지 않게 하라

• API/ABI 호환성은 설계 초기에 반드시 고려해야 한다

• “나중에 고치자”는 API 설계에서 거의 항상 틀린 선택이다

Reference

C++Now 2018: Titus Winters “Modern C++ API Design: From Rvalue-References to Type Design”

API Design Principles - John Pavan - CppNorth 2023

Testability and C++ API Design - John Pavan, Lukas Zhao & Aram Chung - C++Now 2024