1장: API 설계의 진화와 AI 서비스의 도전

학습 목표

• API 패러다임의 역사적 진화 과정을 이해합니다
• AI 서비스가 기존 API 설계에 가져오는 고유한 도전 과제를 파악합니다
• 2026년 현재 하이브리드 아키텍처 트렌드를 학습합니다
• 이 시리즈에서 다룰 내용의 전체 로드맵을 확인합니다

API 패러다임의 진화

소프트웨어 시스템 간의 통신 방식은 지난 25년간 극적으로 변화해 왔습니다. 각 시대의 API 패러다임은 그 시대가 직면한 문제를 해결하기 위해 등장했고, 새로운 요구사항이 생길 때마다 다음 세대의 기술이 탄생했습니다.

SOAP 시대 (2000-2010)

SOAP(Simple Object Access Protocol)은 엔터프라이즈 환경에서 탄생한 최초의 표준화된 웹 서비스 프로토콜입니다. XML 기반의 엄격한 메시지 형식과 WSDL(Web Services Description Language)을 통한 계약 중심 설계가 특징이었습니다.

<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Header>
    <auth:Token xmlns:auth="http://example.com/auth">
      abc123
    </auth:Token>
  </soap:Header>
  <soap:Body>
    <m:GetUserRequest xmlns:m="http://example.com/user">
      <m:UserId>42</m:UserId>
    </m:GetUserRequest>
  </soap:Body>
</soap:Envelope>

SOAP은 트랜잭션 보장, WS-Security 같은 엔터프라이즈 기능을 제공했지만, XML의 장황함과 복잡한 도구 체인이 개발 생산성을 크게 저하시켰습니다.

REST 시대 (2010-2020)

Roy Fielding의 2000년 박사 논문에서 소개된 REST(Representational State Transfer)는 HTTP 프로토콜의 본래 설계 철학을 활용하는 아키텍처 스타일입니다. 리소스 중심의 URL 설계, HTTP 메서드의 시맨틱 활용, JSON 기반의 경량 데이터 교환이 핵심입니다.

# 사용자 목록 조회
GET /api/v1/users?page=1&limit=20
 
# 특정 사용자 조회
GET /api/v1/users/42
 
# 새 사용자 생성
POST /api/v1/users
Content-Type: application/json
{"name": "Kreath", "email": "kreath@example.com"}

REST는 직관적이고 학습 곡선이 낮아 급속히 확산되었습니다. 2026년 현재에도 공개 API의 약 2/3가 REST 기반으로 설계됩니다.

GraphQL의 등장 (2015-)

Facebook이 2015년에 공개한 GraphQL은 클라이언트가 필요한 데이터를 정확히 명시할 수 있는 쿼리 언어입니다. REST의 과도한 데이터 전송(Over-fetching)과 부족한 데이터 전송(Under-fetching) 문제를 해결합니다.

query GetUserWithPosts {
  user(id: "42") {
    name
    email
    posts(first: 5) {
      title
      publishedAt
      tags {
        name
      }
    }
  }
}

2026년 기준으로 약 40%의 팀이 새로운 기능에 GraphQL을 파일럿 도입하고 있으며, 복잡한 데이터 조회에서 평균 180ms의 응답 시간을 달성합니다.

gRPC와 고성능 통신 (2016-)

Google이 개발한 gRPC(gRPC Remote Procedure Call)는 HTTP/2와 Protocol Buffers를 기반으로 한 고성능 RPC 프레임워크입니다. 바이너리 직렬화, 양방향 스트리밍, 코드 자동 생성이 핵심 강점입니다.

syntax = "proto3";
 
service UserService {
  rpc GetUser(GetUserRequest) returns (User);
  rpc ListUsers(ListUsersRequest) returns (stream User);
}
 
message GetUserRequest {
  string user_id = 1;
}
 
message User {
  string id = 1;
  string name = 2;
  string email = 3;
}

gRPC는 마이크로서비스 간 통신에서 REST 대비 약 10배 빠른 25ms 지연시간을 달성하며, CPU 사용량을 40%, 메모리를 30% 절감합니다.

프로토콜 비교: 2026년 현황

AI 서비스의 고유 과제

AI, 특히 LLM(Large Language Model) 기반 서비스는 기존 API 설계 패턴으로는 충분히 대응하기 어려운 고유한 도전 과제를 안고 있습니다.

1. 비결정적 출력

전통적인 API는 동일한 입력에 대해 동일한 출력을 반환합니다. 하지만 LLM은 같은 프롬프트에 대해 매번 다른 응답을 생성할 수 있습니다. 이는 캐싱 전략, 테스트 방법론, 에러 처리 방식에 근본적인 변화를 요구합니다.

// 전통적 API — 결정적 응답
const user = await api.getUser("42");
// 항상 동일한 결과: { id: "42", name: "Kreath" }
 
// AI API — 비결정적 응답
const response = await ai.complete("API 설계 팁을 알려주세요");
// 매번 다른 내용과 형식으로 응답
// temperature, top_p 등의 파라미터로 부분적 제어 가능

2. 긴 응답 시간

일반적인 REST API의 응답 시간이 50-200ms인 반면, LLM API는 500ms에서 5,000ms 이상이 소요됩니다. 이는 타임아웃 설정, 사용자 경험, 로드밸런싱 전략을 재고해야 함을 의미합니다.

3. 토큰 기반 과금

LLM API는 요청 횟수가 아닌 처리된 토큰 수에 따라 과금됩니다. 입력 토큰과 출력 토큰의 가격이 다르며, 모델에 따라 가격 차이가 큽니다. 이는 전통적인 RPS(Requests Per Second) 기반 레이트 리미팅을 토큰 기반으로 전환해야 하는 이유입니다.

4. 스트리밍 응답의 필수화

수 초에 달하는 응답 시간을 사용자가 기다리기는 어렵습니다. 토큰 단위의 스트리밍 응답은 선택이 아닌 필수가 되었으며, SSE(Server-Sent Events) 기반의 표준 스트리밍 프로토콜이 사실상 업계 표준으로 자리잡았습니다.

5. 멀티모달 입력 처리

텍스트뿐만 아니라 이미지, 오디오, PDF 등 다양한 형식의 입력을 하나의 API 요청으로 처리해야 합니다. Content-Type 협상, 파일 크기 제한, 비동기 처리 등 설계 복잡도가 크게 증가합니다.

6. 도구 호출 인터페이스

LLM이 외부 도구를 호출하고 그 결과를 활용하는 Function Calling 패턴은 API 설계에 새로운 차원을 추가합니다. 요청-응답의 단순한 왕복이 아니라, 다단계 대화형 프로토콜이 필요합니다.

하이브리드 아키텍처 트렌드

2026년의 AI 서비스 아키텍처는 단일 프로토콜이 아닌, 각 프로토콜의 강점을 조합한 하이브리드 설계가 주류입니다.

계층별 프로토콜 선택 기준

공개 API 레이어 — REST 또는 GraphQL을 사용합니다. 외부 개발자의 접근성, 브라우저 호환성, 문서화 용이성이 선택 기준입니다. OpenAI, Anthropic 등 주요 AI 서비스 제공자들이 REST를 채택한 것은 이러한 이유에서입니다.

내부 서비스 레이어 — gRPC를 사용합니다. 추론 서비스, 임베딩 서비스 간의 통신에서 바이너리 직렬화와 HTTP/2 멀티플렉싱이 성능 이점을 제공합니다.

비동기 처리 레이어 — 이벤트 스트리밍을 사용합니다. 대규모 배치 추론, 비동기 작업 처리에 Kafka나 SQS 같은 메시지 큐가 적합합니다.

시리즈 로드맵

이 시리즈는 총 11장으로 구성되며, API 설계의 기초부터 AI 서비스 특화 패턴, 그리고 실전 프로젝트까지 포괄적으로 다룹니다.

정리

이 장에서는 API 설계 패러다임이 SOAP에서 REST, GraphQL, gRPC로 진화해 온 과정을 살펴보았습니다. 각 프로토콜은 고유한 강점과 적합한 사용 시나리오를 가지며, 2026년 현재 대부분의 프로덕션 시스템은 이들을 조합한 하이브리드 아키텍처를 채택하고 있습니다.

AI 서비스는 비결정적 출력, 긴 응답 시간, 토큰 기반 과금, 스트리밍 응답, 멀티모달 입력, 도구 호출이라는 고유한 도전 과제를 API 설계에 부여합니다. 이 시리즈를 통해 이러한 과제를 체계적으로 해결하는 방법을 학습하게 됩니다.

다음 장 미리보기

2장에서는 가장 널리 사용되는 API 스타일인 REST의 설계 원칙을 깊이 탐구합니다. Richardson 성숙도 모델, 리소스 설계, HTTP 메서드와 상태 코드의 올바른 사용법, 그리고 AI 서비스에 REST를 적용하는 구체적인 방법을 FastAPI 실습과 함께 다룹니다.