개방형 API(Open API)
1. 개요
가. 정의
개방형 API(Open API) 는 외부 개발자·서비스가 접근·이용할 수 있도록 공개된 표준 인터페이스로, 조직이 보유한 데이터·기능을 개방해 서비스 연계·확장과 생태계(플랫폼) 를 촉진한다.
Open API의 본질은 기술이라기보다 "계약" 에 있다. 내부 구현이 어떻게 바뀌든 외부에 노출된 인터페이스(요청 형식·응답 스키마·인증 방식)만 지키면 되는 약속을 통해, 서로 알지 못하는 조직들이 사전 협의 없이도 시스템을 결합할 수 있게 된다. 이 "표준화된 계약"이야말로 Open API가 개별 연동과 구분되는 핵심이다.
나. 등장 배경 및 필요성
과거 시스템은 폐쇄적이라 외부와 데이터를 주고받으려면 매번 개별 연동(Point-to-Point)을 개발해야 했다. 연동 대상이 n개면 최악의 경우 n×(n−1)개의 연결을 관리해야 하는 조합 폭발이 일어나고, 한 시스템이 바뀌면 연결된 모든 연동을 함께 수정해야 하는 유지보수 부담이 컸다. 이 방식은 참여자가 늘수록 급격히 비효율적이 된다.
디지털 경제에서는 하나의 서비스가 여러 서비스와 결합(매시업, Mashup) 할 때 가치가 커진다. 지도 위에 배달·부동산 정보를 얹거나, 결제·인증·지도를 조합해 새로운 서비스를 만드는 식이다. Open API는 이 결합을 표준 계약으로 만들어, 누구나 정해진 규격에 따라 기능을 호출할 수 있게 한다. 즉 통합 비용을 낮추고 혁신의 속도를 높이는 것이 Open API의 근본 필요성이다.
특히 금융권의 오픈뱅킹·마이데이터는 법·제도로 API 개방을 강제해, Open API가 단순한 기술 선택을 넘어 산업 인프라가 된 대표 사례다. 과거 은행별로 폐쇄되어 있던 계좌·거래 정보가 표준 API로 개방되면서, 핀테크 기업이 여러 금융사의 데이터를 한 앱에서 통합 제공하는 서비스가 가능해졌다. 이는 Open API가 시장 구조 자체를 바꾼 사례다.
다. 특징
Open API의 특징은 곧 그 가치이자 관리 부담이다. 개방·표준·재사용성이 생태계를 키우는 반면, 아무나 호출할 수 있으므로 인증·과금·트래픽 통제가 반드시 수반된다. 즉 "열되, 통제한다"는 이중 명제가 Open API 운영의 본질이며, 이를 균형 있게 달성하는 지점이 곧 API 게이트웨이다.
| 특징 | 내용 | 수반되는 관리 과제 |
|---|---|---|
| 개방성 | 인증된 외부 주체에 기능·데이터 공개 | 접근통제·권한 관리 |
| 표준성 | HTTP·REST·OpenAPI(Swagger) 등 표준 준수 | 명세·버전 관리 |
| 재사용성 | 매시업·플랫폼 생태계 확장 | 개발자 포털·문서화 |
| 통제 필요 | 인증·과금·트래픽 제어 | API 게이트웨이 운영 |
특히 표준성은 Open API가 확산된 결정적 요인이다. HTTP·JSON·OpenAPI 명세라는 공통 언어가 있기에, 서로 다른 언어·플랫폼으로 만들어진 시스템도 별도 어댑터 없이 결합할 수 있다. 표준이 없다면 매 연동마다 형식을 협의해야 하므로 생태계 확장 자체가 불가능하다. 즉 표준성은 재사용성과 개방성을 떠받치는 토대다.
2. Open API 아키텍처와 구성요소
Open API는 클라이언트가 API 서버의 자원을 직접 호출하는 단순 구조로 보이지만, 실제 운영 환경에서는 API 게이트웨이가 중앙 관문 역할을 하며 인증·라우팅·트래픽 제어·로깅을 일괄 담당한다. 아래 구조도는 요청이 게이트웨이를 통과해 처리되는 과정을 보여준다.
flowchart LR
C["클라이언트(앱·서비스)"] -->|HTTPS 요청| G["API 게이트웨이"]
G -->|인증·인가| A["인증서버(OAuth)"]
G -->|Rate Limit·라우팅| S["API 서버(자원)"]
S -->|조회·처리| D[(데이터스토어)]
S -->|JSON 응답| G
G -->|응답·로깅| C
G -.모니터링·통계.-> M["관리·분석 포털"]
게이트웨이를 두는 이유는 횡단 관심사(Cross-cutting Concern)의 일원화 다. 인증·트래픽 제한·버전·로깅을 개별 API마다 구현하면 중복과 불일치가 생기므로, 이를 게이트웨이 한 곳에 모아 정책을 일관되게 적용한다. 개발자 포털은 이 API들을 카탈로그화해 외부 개발자가 명세를 읽고 키를 발급받아 곧바로 사용할 수 있게 하는 셀프서비스 창구 역할을 한다.
핵심 구성요소는 자원(URI로 식별), 행위(HTTP 메서드), 표현(주로 JSON), 인증 토큰(OAuth·JWT), 그리고 이를 감싸는 게이트웨이·포털이다. 이들이 결합해 "누가, 무엇을, 어떻게 호출하고, 어떤 형식으로 응답받는가"라는 계약을 완성한다.
인증·인가는 Open API 운영의 관문이다. 대표 표준인 OAuth 2.0은 사용자의 자격증명(비밀번호)을 제3자 앱에 직접 넘기지 않고, 권한을 위임받은 액세스 토큰만으로 자원에 접근하게 하는 위임 인증 방식이다. 아래 흐름은 클라이언트가 토큰을 발급받아 API를 호출하는 과정을 보여준다.
sequenceDiagram
participant C as 클라이언트
participant Auth as 인증서버
participant API as 자원서버(API)
C->>Auth: 인증·권한요청(scope)
Auth->>C: 액세스 토큰 발급
C->>API: 토큰과 함께 자원 요청
API->>API: 토큰 검증·권한 확인
API->>C: JSON 응답
이 방식의 핵심 이점은 최소 권한과 폐기 용이성이다. 토큰에는 접근 범위(scope)와 만료 시간이 담겨, 탈취되더라도 피해 범위와 기간이 제한된다. 또 토큰만 회수하면 권한을 즉시 철회할 수 있어 비밀번호 공유 방식보다 훨씬 안전하다. 실무에서는 여기에 OIDC(OpenID Connect)를 얹어 인증(누구인가)까지 표준화한다.
3. SOAP와 REST 구성요소 비교
Open API를 구현하는 두 방식이 SOAP와 REST다. 둘의 근본 차이는 SOAP은 엄격한 XML 프로토콜이고 REST는 HTTP를 그대로 활용하는 아키텍처 스타일이라는 점이다. 이 차이가 성능·신뢰성·개발 편의의 트레이드오프를 만든다.
SOAP은 표준이 강하고 WS-Security·트랜잭션(WS-AtomicTransaction)을 갖춰 은행 간 거래처럼 높은 신뢰성과 보안이 필요한 곳에 맞는다. 메시지가 XML Envelope로 무겁게 감싸지고 WSDL로 인터페이스를 엄격히 정의하므로 계약이 명확하지만, 그만큼 오버헤드가 크고 유연성이 떨어진다. 반면 REST는 자원을 URI로 표현하고 HTTP 메서드(GET·POST·PUT·DELETE)로 다뤄 가볍고, 무상태(Stateless)라 수평 확장이 쉬우며 HTTP 캐싱을 그대로 활용할 수 있다.
이러한 차이 때문에 오늘날 공개 API 대부분은 REST(또는 그 대안인 GraphQL)로 제공된다. 웹·모바일 환경에서는 경량·캐싱·확장성이 결정적 이점이기 때문이다. 다만 강한 트랜잭션 보장과 표준 보안이 필요한 기업 간(B2B)·레거시 연계에서는 여전히 SOAP이 쓰인다. 즉 "REST가 항상 옳다"기보다 요구사항(신뢰성 vs 경량성)에 따라 선택하는 것이 실무적 판단이다.
| 구분 | SOAP | REST |
|---|---|---|
| 개념 | XML 기반 프로토콜 | HTTP 기반 아키텍처 스타일 |
| 구성요소 | Envelope·Header·Body, WSDL, UDDI | 자원(URI)·HTTP 메서드·표현(JSON)·무상태 |
| 메시지 | XML | 주로 JSON |
| 보안·트랜잭션 | WS-Security·WS-Transaction 내장 | HTTPS·OAuth 등 별도 조합 |
| 특징 | 강한 표준·트랜잭션·신뢰성 | 경량·확장성·캐싱·Stateless |
| 적합 | 엔터프라이즈·고신뢰·B2B | 웹·모바일·공개 API |
4. 취약점 및 대응 방안 (OWASP API Security Top 10)
Open API는 외부에 노출되므로 웹 애플리케이션과는 다른 API 특유의 위협을 받는다. 그중 가장 흔하고 치명적인 것이 BOLA(Broken Object Level Authorization, 객체 수준 인가 미흡) 인데, 인증은 통과했지만 "남의 데이터에 접근할 권한"까지 검증하지 않아 URL의 식별자만 바꾸면 타인 정보가 조회되는 결함이다.
예컨대 로그인한 사용자가 /orders/1001을 /orders/1002로 바꿔 남의 주문을 조회하는 식이다. 인증(누구인가)은 확인했으나 인가(이 자원에 접근해도 되는가)를 자원 단위로 검증하지 않은 것이 원인이다. 따라서 요청마다 해당 객체의 소유·권한을 서버가 재검증해야 하며, 클라이언트가 보낸 ID를 그대로 신뢰해서는 안 된다. BOLA가 OWASP API Top 10에서 반복적으로 1위를 차지하는 이유는, 기능은 정상 동작하므로 테스트에서 잘 드러나지 않고 배포 후에야 악용되기 때문이다.
BOLA 외에도 인증 취약(Broken Authentication), 과도한 데이터 노출, 자원 고갈(무제한 호출로 인한 DoS), 인젝션, 방치된 구버전 API 노출 등이 주요 위협이다. 이들은 대부분 "서버가 클라이언트 입력을 신뢰했다"는 공통 원인을 가지므로, 대응의 핵심은 모든 입력·요청·권한을 서버가 독립적으로 검증하는 것이다.
| 취약점 | 원리 | 대응 |
|---|---|---|
| 객체 인가 미흡(BOLA) | 객체 소유권 미검증 | OAuth 2.0·JWT + 객체 수준 권한 검증 |
| 인증 취약 | 약한 토큰·세션 관리 | 표준 인증(OAuth·OIDC), 토큰 만료·회전 |
| 과도한 데이터 노출 | 응답에 불필요 필드 포함 | 응답 필드 최소화, 스키마 검증 |
| 자원 고갈(DoS) | 무제한 호출·대량 조회 | Rate Limiting·쿼터, 페이지네이션 |
| 인젝션 | 미검증 입력이 쿼리로 실행 | 입력 검증, 파라미터 바인딩 |
| 부적절한 자산관리 | 방치·구버전 API 노출 | API 인벤토리·버전 관리, 폐기 API 차단 |
실제로 여러 대형 플랫폼에서 BOLA·과도한 데이터 노출로 수백만 건의 개인정보가 유출된 사고가 반복되었으며, 이는 API 보안이 네트워크 방화벽이 아니라 애플리케이션 로직 계층의 문제임을 보여준다. 방화벽·WAF는 인증을 통과한 정상 요청 안에 담긴 인가 결함을 판별하지 못하기 때문에, API 보안은 반드시 서비스 로직에 내재화되어야 한다.
5. API 관리(수명주기)
Open API는 한 번 공개하면 끝이 아니라, 외부 이용자가 의존하므로 설계부터 폐기까지 신중히 관리해야 한다. 갑자기 API를 바꾸면 이를 쓰던 모든 서비스가 깨지기 때문이다. 그래서 설계 단계에서 OpenAPI 명세로 계약을 먼저 정하고(계약 우선, Contract First), 게이트웨이·포털로 게시·운영하며, 폐기 시에는 충분한 유예와 마이그레이션 안내를 둔다.
flowchart LR
P["설계(OpenAPI 명세)"] --> B["게시(게이트웨이·포털)"]
B --> O["운영(인증·과금·모니터링)"]
O --> V["버전관리(하위호환)"]
V --> R["폐기(유예·마이그레이션)"]
O -.피드백.-> P
수명주기에서 가장 민감한 지점은 버전 관리다. 하위 호환을 깨는 변경(필드 삭제, 응답 형식 변경)은 새 버전(/v2)으로 분리하고, 기존 버전은 폐기 예고(Deprecation) 후 유예기간을 두어 이용자가 마이그레이션할 시간을 준다. 이 원칙을 지키지 않으면 개방 생태계의 신뢰가 무너져, 외부 개발자가 API 채택 자체를 꺼리게 된다.
운영 단계에서는 모니터링과 SLA(서비스 수준 협약) 관리가 중요하다. 외부 이용자는 API의 가용성·응답시간에 자기 서비스를 의존하므로, 게이트웨이가 수집한 호출량·오류율·지연 지표를 상시 관측하고 이상 징후를 조기에 탐지해야 한다. 또 이용 등급별로 호출 한도(쿼터)와 과금 정책을 차등 적용해, 특정 이용자의 폭주가 전체 서비스 품질을 떨어뜨리지 않도록 격리한다.
| 단계 | 활동 |
|---|---|
| 설계 | OpenAPI 명세(계약 우선), 표준화 |
| 게시 | API 게이트웨이·개발자 포털 등록 |
| 운영 | 인증·과금·모니터링·트래픽 제어 |
| 버전관리 | 하위호환 유지, 새 버전 분리 |
| 폐기 | 폐기 예고·유예·마이그레이션 안내 |
6. 심화: 최신 동향과 표준
Open API 생태계는 REST를 기반으로 하면서도 새로운 요구에 맞춰 진화하고 있다. 기술사 관점에서 아래 흐름을 함께 이해해야 한다.
- GraphQL·gRPC의 부상: REST가 자원마다 고정된 응답을 주는 것과 달리 GraphQL은 클라이언트가 필요한 필드만 질의해 과도한/부족한 데이터 전송(Over/Under-fetching)을 해결한다. 반면 마이크로서비스 내부 통신에서는 성능이 중요해 HTTP/2 기반 이진 프로토콜인 gRPC가 확산된다. 즉 공개 API는 REST/GraphQL, 내부 통신은 gRPC로 분화되는 경향이다.
- API 게이트웨이·API 관리(APIM) 고도화: 단순 라우팅을 넘어 인증·정책·과금·분석을 통합한 상용/오픈소스 APIM(Kong, Apigee 등)이 표준 인프라가 되었고, 서비스 메시(Istio)와 결합해 내부 트래픽까지 통제한다.
- 제로트러스트·mTLS 적용: "내부망도 신뢰하지 않는다"는 제로트러스트 원칙에 따라, API 구간을 mTLS(상호 TLS) 로 상호 인증하고 모든 호출을 검증·로깅하는 방향으로 보안이 강화되고 있다.
- 국내 개방 정책의 확대: 오픈뱅킹·마이데이터에서 시작된 API 개방이 공공데이터 포털, 행정정보 공동이용 등으로 확산되며, Open API가 데이터 경제의 핵심 인프라로 자리 잡고 있다.
- API 우선(API-First)·문서 자동화: 서비스를 기획할 때 API를 최우선 산출물로 설계하는 API-First 문화가 확산되면서, OpenAPI 명세로부터 문서·SDK·테스트를 자동 생성해 일관성과 생산성을 동시에 확보하는 방식이 표준이 되고 있다.
7. 고려사항 및 시사점
- 게이트웨이 중심 통제: 인증·트래픽 제한·버전·로깅을 개별 API마다 구현하는 대신 API 게이트웨이로 일원화해, 보안·운영을 일관되게 적용하고 개별 서비스의 부담을 줄인다.
- 계약 우선(Contract First): OpenAPI 명세를 먼저 확정하면 문서·목서버(Mock)·클라이언트 코드를 자동 생성할 수 있어 개발 생산성과 프론트·백엔드 병렬 개발이 가능해진다.
- 보안은 애플리케이션 계층의 문제: 방화벽만으로는 BOLA 같은 로직 결함을 막을 수 없다. 요청마다 객체 수준 권한을 검증하고, 제로트러스트·mTLS로 구간을 보호해야 한다.
- 거버넌스와 생태계 전략: Open API는 기술이자 비즈니스 전략이다. 어떤 데이터를 개방해 어떤 파트너 생태계를 키울지, 과금·SLA를 어떻게 설계할지가 곧 플랫폼 경쟁력이 된다. 오픈뱅킹·마이데이터처럼 개방이 시장 구조를 바꿀 수 있음을 고려해야 한다.
- 표준 선택의 트레이드오프: REST·GraphQL·gRPC·SOAP은 각각 경량성·유연성·성능·신뢰성에서 강점이 다르다. "무엇이 최신인가"가 아니라 대상(공개/내부), 요구(신뢰성/성능), 이용자 역량을 종합해 선택해야 하며, 하나의 시스템 안에서도 계층별로 서로 다른 프로토콜을 혼용하는 것이 일반적이다.
참고자료
- OWASP API Security Top 10 — https://owasp.org/API-Security/
- OpenAPI Specification (Swagger) — https://spec.openapis.org/oas/latest.html
- 금융결제원 오픈뱅킹 — https://www.open-platform.or.kr/
한 줄 요약: 개방형 API는 표준(REST/SOAP·OpenAPI) 기반의 "공개된 계약"으로 매시업·플랫폼 생태계를 확장하며, OAuth·객체 수준 권한 검증·게이트웨이·Rate Limiting으로 OWASP API 취약점(특히 BOLA)에 대응하고, 계약 우선·버전·폐기의 수명주기 관리와 제로트러스트·mTLS로 운영하는 오픈뱅킹·마이데이터의 기반 인프라다.