[기술 공부] API Fundamentals

용어 정리

API

API(Application Programming Interface) 란,하나의 소프트웨어 응용 프로그램(Application) 이 다른 소프트웨어나 컴포넌트와 프로그래밍 방식(Programming) 으로 상호작용할 수 있도록 정의된 접점 또는 규칙(Interface) 의 집합.

• Application
  • 소프트웨어 응용 프로그램
  • 어떤 목적을 수행하기 위한 하나의 실행 가능한 소프트웨어 유닛
  • 사용자 또는 다른 프로그램이 사용하는 대상
• Programming
  • 컴퓨터가 수행할 작업을 정의하는 논리적 명령의 집합을 작성하는 행위
  • 개발자가 특정 동작을 제어하거나, 호출하기 위한 코드 작성 활동을 의미.
• Interface
  • 두 시스템간의 경계면 또는 접점
    서로 다른 컴포넌트나 시스템이 어떻게 소통할 수 있는지를 정의한 명세

API 명세 (API Contract)

API 소비자(Client) 와 제공자(Server) 사이에 어떻게 통신할지 명시적으로 정의한 약속 또는 규칙 집합 입니다. 요청 형식, 응답 구조, 허용 매서드, 오류 처리 방식 등을 포함하는 문서화된 계약입니다.

항목	설명
Endpoint	호출할 URL 및 리소스 경로 (/users/{id} 등)
HTTP Method	허용된 요청 방식 (GET, POST, PUT, DELETE 등)
Request Schema	요청 시 필요한 파라미터, 바디의 형식 및 필수 여부
Response Schema	응답의 구조, 필드, 데이터 타입, 예시 값
Status Codes	요청에 대한 결과 상태 (200, 400, 404, 500 등)
에러 메시지 구조	오류 발생 시 표준화된 응답 포맷 (예: problem+json, custom JSON)
Authentication	인증 방식 (JWT, OAuth2, API Key 등)

IDL (Interface Definition Language)

시스템간 데이터 구조와 인터페이스를 명확하게 정의하는 중립적 기술 언어 ➡️ API가 어떤 요청 / 응답 구조를 가질지 컴퓨터가 이해 가능하게 명세

• 종류
  • Protocol Buffers(.proto ➡️ gRPC에서 사용)
  • Thrift
  • OpenAPI(YAML/JSON)
• 목적
  • 자동화된 코드 생성 (Client / Server Stup)
  • 스키마 기반 검증

Schema(DSL) First 🆚 Example First

방식	설명
Schema First	OpenAPI/GraphQL SDL 등에서 타입과 구조를 먼저 선언하고 API 개발
Example First	예시 요청/응답부터 작성 → 후속적으로 스키마를 추론하거나 문서화

• REST API는 정형화된 구조와 문서화 도구가 잘 갖춰져 있어 Schema First 방식이 일반적임. But, 초기 설계가 유동적이거나 빠르게 클라이언트와 커뮤니케이션 해야 하는 경우 Example First도 사용하기도 함.
  • 주로 사용되는 경우
    • 빠르게 UI/클라이언트 팀과 협업할 때
    • 기획이 확정되지 않았을 때
    • 비개발자와 협업하거나 프토토타입이 중심일 때

Postel's Law(Robustness Principle)

발신자는 명확하게, 수신자는 유연하게 설계하라.

• API 수신 측에서 알 수 없는 필드나 순서가 다른 필드를 무시하도록 허용함.
• 엄격한 스키마 검증이 필요한 보안 API에는 부적합함.
• GraphQL같은 스키마 기반 API는 이 원칙을 덜 따름.

• 1980년대 초, 인터넷 프로토콜 초창기
  • 저 위에 개발 잘하게 생긴 아저씨가 TCP/IP 표준을 만드는 핵심 인물이었음
  • 당시 네트워크 장비나 소프트웨어는 버그랑 호환성 문제가 많았음
  • 수신측이 엄격해서, 사소한 차이로도 통신거부함 ➡️ 인터넷 확산 장애
  • 그래서 조금 이상해도 받아주자 ➡️ 시스템간 상호운용성(interoperability)확보 ➡️ 보내는쪽은 표준을 꼭 지켜라 ➡️ 혼란 방지
• 그래서 이게 뭔말이냐면
  • 클라이언트가 id, name만 쓰기로 설계되어있음.
  • 서버에서 nickname을 추가했지만, 클라이언트는 무시하고 계속 정상동작 할 수 있어야함.

// 서버 응답
{
  "id": 123,
  "name": "Junha",
  "nickname": "J"
}

이점	한계
상호운용성 향상	버그 은폐: 잘못된 입력도 수용되므로 버그가 감춰짐
낮은 중단 가능성	사양 혼란: 명확하지 않은 API 스펙이 생김
오래된 클라이언트 호환	보안 취약성 가능성 증가

현대 API 설계에서는 Postel's Law를 부분 수용합니다.

• JSON이나 REST API에서는
  • 받는 쪽은 불필요한 필드를 무시하도록 설계 (👍 유연성)
  • 보내는 쪽은 엄격하게 필드 타입, 필수 여부를 체크 (👍 명확성)

하지만,

• GraphQL, gRPC, OpenAPI 기반 스키마 중심 설계에선 오히려 엄격한 유효성 검사가 권장됨
  → “Schema-first 설계 철학”이 Postel's Law와 대립되기도 함

Version - tolerant Serialization

스키마가 변경되더라도 직렬화/역직렬화가 실패하지 않도록 설계

• 메시지(데이터)의 필드가 추가/삭제/순서 바뀌어도 구버전 클라이언트가 무시하고 처리 가능

• 일반적으로 직렬화 포맷(Protocol Buffers, Thrift 등)이 제공

• 코드나 시스템 설계가 아닌, 데이터 포맷의 기능

Backward Compatibility

이전 버전의 API 클라이언트가 새 버전 서버에서도 정상 동작해야함.

• Backwards Compatible API를 만들기 위해서는 내부적으로 version tolerant한 직렬화 포멧이 뒷받침되어야 함.
• version tolerant serialization이 있다고 해서 전체 API가 backwards-compatible 하다는 보장은 없음.

• 클라이언트가 오래된 요청 구조를 써도 에러 없이 응답을 받아야 함.
• 응답 구조, 동작 방식 등을 깨지 않도록 조심스럽게 변경해야 함.
• 일반적으로 API 설계자가 책임.

// Old version
message User {
  string name = 1;
}

// New version
message User {
  string name = 1;
  string nickname = 2;  // optional field
}

• v1 응답에 nickname 필드를 새로 추가했지만, 기존 클라이언트는 무시할 수 있음
• 필수 필드를 삭제하거나 이름을 바꾸는 건 안됨.
  
  
  
• version-tolerant serialization: nickname이 없더라도 메시지를 깨지 않고 처리함.
• backward-compatible API 설계: 이 구조가 그대로 유지되고, 기존 클라이언트가 nickname을 무시해도 문제 없이 동작해야 함.

즉. “Version-tolerant serialization은 메시지 수준에서 필드 추가·삭제 등 스키마 변화에 유연하게 대처할 수 있는 기술입니다. 반면 Backward Compatibility는 전체 API 수준에서 이전 클라이언트가 여전히 정상 동작할 수 있도록 보장하는 설계 원칙입니다. 전자는 구현, 후자는 설계 철학이라 할 수 있습니다.”

Error Envelope (오류 응답 구조)

오류 발생시에도 예측 가능한 공통 포멧으로 응답.

{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "User with ID 999 not found.",
    "details": { "userId": 999 }
  }
}

• RFC 9457 (formerly 7807) – application/problem+json

• 에러 응답을 표준화하면 클라이언트의 오류 처리 코드를 단순화 할 수 있음.

Design-by-Contract 원칙

컴포넌트간의 입력 전제조건, 출력 보장조건, 불변성을 계약처럼 정의하는 방식

• API 측면에서
  • 요청자 : 계약을 준수해야함
  • 제공자 : 계약된 출력을 보장해야함
• 테스트/문서화/오류검증을 위한 설계 패러다임.
• 즉, API의 예측 가능성과 안정성을 높이기 위한 철학. OpenAPI 스펙은 이를 문서화한 사례