길리랩blog

API란 무엇인가: 유형별 비교부터 아키텍처·보안·운영까지

REST·SOAP·GraphQL의 차이, API 게이트웨이·마이크로서비스 아키텍처, 인증·보안 위협 대응, 라이프사이클·모니터링·테스트 전략을 실무 사례와 함께 정리한다.

2026-08-13 · 최초 발행 2025-05-23

API(Application Programming Interface)는 애플리케이션 간의 상호작용을 가능하게 하는 소프트웨어 중개자다. 복잡한 코드 작성 없이도 다른 소프트웨어 구성요소와 통신할 수 있게 해주는 메커니즘이다.

API의 핵심 요소는 API 서버의 특정 리소스에 접근할 수 있는 URL인 엔드포인트(Endpoint), 요청 시 함께 전달되는 추가 정보인 파라미터(Parameter), 인증·접근 제어를 위한 고유 식별자인 API 키(Key), 주로 JSON·XML 등 표준화된 형식으로 데이터를 제공하는 응답 형식(Response Format)이다. API 구성 요소는 클라이언트가 서버에 전송하는 메시지인 요청(Request), 서버가 클라이언트에 반환하는 결과인 응답(Response), API 사용법을 설명하는 문서화(Documentation)로 나뉜다.

REST·GraphQL·gRPC가 계약을 표현하는 방식

REST(Representational State Transfer)는 웹 서비스를 설계하는 아키텍처 스타일로, 리소스 중심의 접근 방식을 채택한다. 무상태(Stateless)로 각 요청을 독립적으로 처리하고, HTTP 메소드(GET, POST, PUT, DELETE 등)를 활용하는 균일한 인터페이스를 갖추며, URL로 리소스를 식별하는 리소스 기반 구조다.

GET /api/users/123 HTTP/1.1
Host: example.com
Accept: application/json

REST API는 단순성과 확장성 때문에 널리 사용되지만, 복잡한 데이터 요구 사항에는 비효율적일 수 있다.

SOAP(Simple Object Access Protocol)은 XML 기반의 메시지 프로토콜로, 엄격한 규칙을 따른다. HTTP·SMTP 등 다양한 프로토콜을 지원하는 프로토콜 독립성, WS-Security 등 내장 표준을 지원하는 높은 보안성, WSDL(Web Services Description Language)로 인터페이스를 정의하는 엄격한 계약이 특징이다.

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <GetUserRequest>
      <UserId>123</UserId>
    </GetUserRequest>
  </soap:Body>
</soap:Envelope>

금융, 통신 등 보안이 중요한 엔터프라이즈 환경에서는 SOAP의 안정성과 보안성이 여전히 가치를 인정받는다.

GraphQL은 페이스북이 개발한 쿼리 언어로, 클라이언트가 필요한 데이터만 정확히 요청할 수 있게 해준다. 모든 요청이 하나의 URL로 전송되는 단일 엔드포인트, 오버페칭·언더페칭 문제를 해결하는 필요한 데이터만 요청하는 구조, 명확한 데이터 구조를 정의하는 강력한 타입 시스템이 특징이다.

query {
  user(id: "123") {
    name
    email
    posts {
      title
      createdAt
    }
  }
}

Netflix, GitHub, Airbnb 등은 GraphQL을 도입해 복잡한 데이터 요구사항을 효율적으로 처리하고 있다.

게이트웨이 뒤에서 서비스를 묶는 구조

API 게이트웨이는 클라이언트와 백엔드 서비스 사이의 중개자 역할을 한다.

⤢✕클라이언트API 게이트웨이마이크로서비스 1마이크로서비스 2마이크로서비스 3

주요 기능은 요청을 적절한 서비스로 전달하는 라우팅, 접근 제어를 관리하는 인증/인가, 트래픽을 조절하는 속도 제한, 응답 데이터를 저장하는 캐싱, 데이터 포맷을 변환하는 응답 변환이다. Amazon API Gateway, Kong, Azure API Management 등이 API 게이트웨이의 대표적인 예다.

마이크로서비스는 작고 독립적인 서비스로 애플리케이션을 구성하는 접근 방식이다.

⤢✕API Layer사용자 서비스주문 서비스결제 서비스재고 서비스

API 설계 고려사항은 서비스 위치를 자동 감지하는 서비스 발견(Service Discovery), 장애 전파를 막는 회로 차단기(Circuit Breaker), 하위 호환성을 유지하는 버전 관리, 일부 서비스가 실패해도 전체 시스템이 작동하는 내결함성이다.

토큰과 서명으로 지키는 API

인증과 인가에서 OAuth 2.0은 외부 서비스에 제한된 접근 권한을 부여하는 표준 프로토콜로, 인증 코드 흐름(Authorization Code Flow), 암시적 흐름(Implicit Flow), 클라이언트 자격 증명 흐름(Client Credentials Flow)으로 나뉜다. JWT(JSON Web Token)는 당사자 간에 정보를 안전하게 전송하기 위한 컴팩트한 형식이다.

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.
eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.
SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

일반적인 보안 위협과 대응으로는 입력 검증·매개변수화된 쿼리로 막는 인젝션 공격, 민감한 데이터를 필터링해야 하는 과도한 데이터 노출, 과도한 요청을 차단하는 속도 제한(Rate Limiting), 교차 출처 요청을 제어하는 CORS(Cross-Origin Resource Sharing)가 있다.

설계부터 폐기까지, API의 생애주기

API 라이프사이클 관리는 요구사항 분석·API 설계를 하는 계획 및 설계, 구현·테스트를 하는 개발, 스테이징·프로덕션 환경으로 옮기는 배포, 버전 관리·사용 분석을 하는 관리, 레거시 API를 단계적으로 폐지하는 폐기로 이어진다.

API 모니터링의 주요 지표는 요청 처리 시간인 지연 시간(Latency), 단위 시간당 처리 요청 수인 처리량(Throughput), 실패한 요청 비율인 오류율(Error Rate), 서비스 접근 가능 시간 비율인 가용성(Availability)이다. 모니터링 도구로는 메트릭 수집·시각화를 맡는 Prometheus·Grafana, 로그 집계·분석을 맡는 ELK Stack, 종합적인 애플리케이션 모니터링을 맡는 New Relic·Datadog이 있다.

무너지지 않는지 검증하는 방법

테스트 유형은 개별 API 엔드포인트를 검사하는 단위 테스트, 여러 API 간 상호작용을 검사하는 통합 테스트, 대량 요청 처리 능력을 검증하는 부하 테스트, 취약점을 검사하는 보안 테스트로 나뉜다.

테스트 자동화 도구로는 API 테스트·문서화 도구인 Postman, 부하 테스트 도구인 JMeter, 명령줄 기반 Postman 컬렉션 실행기인 Newman, API 명세·테스트 자동화를 지원하는 Swagger/OpenAPI가 있다.

⤢✕개발테스트 자동화CI/CD 파이프라인배포모니터링

성공과 실패가 남긴 교훈

Twilio는 통신 API를 통해 SMS, 음성, 비디오 서비스를 제공한다. 복잡한 통신 인프라를 간단한 API로 추상화하고, 개발자 친화적인 문서와 SDK를 제공한 것이 성공 요인이다. Stripe는 결제 처리 API로, 복잡한 결제 프로세스를 단순화한 API 설계와 명확한 오류 메시지·디버깅 도구가 강점이다.

반면 Twitter API 변경은 갑작스러운 API 정책 변경으로 많은 서드파티 앱 개발자의 반발을 불러왔다. API 변경 시 충분한 예고와 마이그레이션 경로 제공이 필요하다는 교훈을 남겼다. Facebook Graph API v1.0 중단은 하위 호환성 없는 변경으로 많은 앱이 중단된 사례로, 적절한 버전 관리와 점진적 변경의 중요성을 보여줬다.

API를 수익으로 바꾸는 방식과 시장

API 수익화 전략은 요청 수에 따라 과금하는 유료 API 모델(예: Google Maps API), 기본 기능은 무료·고급 기능은 유료인 프리미엄 모델(예: Dropbox API), API를 통한 생태계 확장으로 간접 수익을 만드는 간접 수익 모델(예: AWS)로 나뉜다.

API 시장 현황은 RapidAPI·ProgrammableWeb 같은 공개 API 디렉토리, 기업의 핵심 제품으로서의 API인 API-as-a-Product, 조직 내 마이크로서비스 간 통신을 위한 내부 API 경제로 구성된다.

다음 흐름은 어디로 향하는가

실시간 데이터 처리를 위한 웹훅·스트리밍 API가 늘어나는 이벤트 기반 API, 클라우드 기반 서버리스 아키텍처를 활용하는 서버리스 API, 인공지능 기능을 제공하는 API가 확산하는 AI 통합 API(예: OpenAI API), 사물인터넷 기기 연결을 위한 특화된 IoT API가 미래 트렌드로 꼽힌다.

API는 현대 소프트웨어 생태계의 근간으로, 서로 다른 시스템과 서비스를 연결하는 핵심 역할을 한다. 효과적인 API 설계와 관리는 보안·확장성·사용 편의성을 균형 있게 고려하는 일이며, 단순한 기술적 인터페이스를 넘어 새로운 비즈니스 기회와 혁신의 촉매로 작동한다.

APIRESTGraphQLAPI게이트웨이마이크로서비스