API란? 인터페이스부터 Public API와 Private API까지

프론트엔드에서 서버의 데이터를 조회하거나, 지도 서비스에서 위치를 검색하거나, 소셜 계정으로 로그인할 때 우리는 API를 사용한다.

API는 서로 다른 프로그램을 연결하는 접점이다. 하지만 API를 단순히 “서버와 통신하는 방법”으로만 이해하면 라이브러리 API나 운영체제 API 같은 개념을 설명하기 어렵다. 먼저 더 넓은 개념인 인터페이스부터 살펴보자.

이 글은 인프런의 큰돌님의 CS 지식 강의를 학습한 뒤, 관련 개념과 예제를 보완해 재구성한 내용입니다.

인터페이스란?

인터페이스(Interface)는 서로 다른 두 대상이 상호작용할 수 있도록 정한 접점과 규칙이다.

사용자는 자동차 내부의 복잡한 동작을 몰라도 핸들과 페달을 이용해 자동차를 조작할 수 있다. 핸들과 페달이 운전자와 자동차 사이의 인터페이스 역할을 하기 때문이다.

소프트웨어에서도 같은 개념이 적용된다.

• 사용자가 화면의 버튼을 통해 프로그램을 조작하는 사용자 인터페이스(UI)
• 클래스가 제공해야 할 메서드를 선언하는 프로그래밍 언어의 인터페이스
• 프로그램이 운영체제의 기능을 요청하는 시스템 콜 인터페이스
• 서로 다른 프로그램이 기능과 데이터를 주고받는 API

인터페이스는 내부 구현 전체를 공개하는 것이 아니라, 상대방이 이용하는 데 필요한 사용 방법을 제공한다.

API란?

API(Application Programming Interface)는 한 소프트웨어가 다른 소프트웨어의 기능이나 데이터에 접근할 수 있도록 제공하는 규칙과 수단의 집합이다.

API를 제공하는 쪽은 사용할 수 있는 기능과 호출 방법을 정의하고, 사용하는 쪽은 그 규칙에 맞춰 요청한다.

API 사용자(Client)
        ↓ 정해진 규칙에 따른 요청
       API
        ↓ 내부 로직 호출
API 제공자(Server, Library, OS 등)
        ↓ 정해진 형식의 결과
API 사용자(Client)

웹 API는 HTTP를 이용하는 API의 한 종류일 뿐이다. API에는 다음과 같은 형태도 있다.

• JavaScript의 Array.prototype.map()과 같은 라이브러리 API
• 브라우저가 제공하는 DOM API
• 운영체제가 제공하는 시스템 API
• HTTP를 통해 서버의 기능을 제공하는 Web API

따라서 모든 API가 네트워크를 통해 통신하는 것은 아니다.

API는 일종의 계약이다

API를 사용하려면 제공자와 사용자가 동일한 규칙을 이해해야 한다. 이 규칙을 API 계약(Contract)이라고 한다.

웹 API의 계약에는 일반적으로 다음 내용이 포함된다.

• 요청을 보낼 주소(Endpoint)
• 요청 방식(GET, POST, PUT, DELETE 등)
• 경로·쿼리·본문에 전달할 값
• 요청과 응답의 데이터 형식
• 인증 방법
• 성공 응답과 오류 응답의 구조
• 호출 횟수 제한(Rate Limit)

예를 들어 사용자 한 명을 조회하는 API 계약은 다음과 같이 표현할 수 있다.

GET /api/users/42
Authorization: Bearer <access-token>

{
  "id": 42,
  "name": "woojin",
  "email": "woojin@example.com"
}

클라이언트는 서버가 사용한 데이터베이스 종류나 내부 조회 로직을 몰라도 API 계약만 지키면 기능을 사용할 수 있다.

API가 필요한 이유

1. 내부 구현을 감출 수 있다

API 제공자는 데이터베이스 구조, 내부 알고리즘, 서버 구성 등 서비스의 세부 구현을 모두 노출할 필요가 없다. 사용자는 공개된 입력과 출력 규칙만 알면 된다.

이를 추상화와 캡슐화라고 한다. 다만 내부 구현을 감추는 것만으로 보안이 완성되는 것은 아니다. 인증, 인가, 입력값 검증 등의 보안 장치가 별도로 필요하다.

2. 구현과 사용을 분리할 수 있다

API 계약이 유지된다면 제공자는 내부 코드를 수정하거나 데이터베이스를 교체할 수 있다. 사용자는 내부 구현의 변화에 직접 대응하지 않아도 된다.

반대로 계약 자체가 바뀌면 기존 사용자가 영향을 받을 수 있으므로 버전 관리와 하위 호환성이 중요하다.

/api/v1/users
/api/v2/users

3. 기능을 재사용할 수 있다

로그인, 결제, 지도, 알림처럼 이미 구현된 기능을 API로 연결하면 처음부터 모두 개발하지 않아도 된다. 개발 시간과 비용을 줄이고 핵심 기능에 집중할 수 있다.

4. 여러 클라이언트에 동일한 기능을 제공할 수 있다

하나의 API를 웹, 모바일 앱, 관리자 페이지 등 여러 클라이언트에서 사용할 수 있다. 서버가 데이터를 한곳에서 관리하므로 일관된 결과를 제공하기도 쉽다.

5. 시스템을 독립적으로 나눌 수 있다

각 시스템이 API 계약을 기준으로 통신하면 팀이나 서비스 단위로 기능을 분리할 수 있다. 마이크로서비스 환경에서도 서비스 사이의 명확한 경계로 활용된다.

API의 공개 범위에 따른 종류

API는 누구에게 공개하는지에 따라 Public, Private, Partner API 등으로 나눌 수 있다.

Public API

Public API는 외부 개발자가 사용할 수 있도록 공개한 API다. Open API라고도 부르지만, 무료이거나 인증 없이 사용할 수 있다는 뜻은 아니다.

Public API는 보통 다음과 같은 방식으로 관리한다.

• API Key 또는 OAuth를 이용한 인증
• 사용자나 애플리케이션별 호출 횟수 제한
• 사용량 모니터링과 과금
• 개발자 문서와 변경 이력 제공
• 악용을 방지하기 위한 권한 및 정책 적용

예를 들면 공공데이터 API, 지도 API, 결제 API 등이 있다.

Private API

Private API는 조직이나 서비스 내부에서만 사용하는 API다. Internal API라고도 한다.

예를 들어 쇼핑몰의 주문 서비스가 재고 서비스에 상품 수량을 확인하거나, 사내 관리자 페이지가 내부 회원 API를 호출하는 경우가 이에 해당한다.

Private API는 다음과 같은 방법으로 접근을 제한할 수 있다.

• 사설 네트워크 또는 VPN
• 서비스 계정과 접근 토큰
• 방화벽과 IP 허용 목록
• 역할 기반 접근 제어(RBAC)
• mTLS와 같은 서비스 간 인증

API Key를 애플리케이션 코드에 하드코딩하는 방식은 키가 노출될 수 있으므로 피해야 한다. 비밀값은 환경 변수나 별도의 비밀 관리 시스템을 이용해 관리하는 것이 안전하다.

Partner API

Partner API는 불특정 다수가 아니라 계약을 맺은 특정 협력사에만 제공하는 API다. Public API보다 접근 범위가 좁고, 파트너마다 별도의 권한과 사용량 정책을 적용하는 경우가 많다.

공개 범위와 관계없이 민감한 기능에는 적절한 인증과 인가가 필요하다. “내부 API이므로 안전하다”라고 가정해서는 안 된다.

API와 데이터 형식의 관계

API는 프로그램 사이의 상호작용 규칙이고, JSON이나 XML은 요청과 응답의 데이터를 표현하는 형식이다. 두 개념은 서로 관련되어 있지만 같은 것은 아니다.

API: 어디로, 어떻게 요청하고 어떤 응답을 받을 것인가?
JSON/XML: 요청과 응답 데이터를 어떤 구조로 표현할 것인가?

오늘날의 웹 API에서는 JSON을 많이 사용하지만 XML, HTML, 이미지, 파일 등도 응답으로 전달할 수 있다. JSON과 XML의 자세한 차이는 JSON, XML, HTML의 차이와 데이터 교환 형식에서 확인할 수 있다.

정리

• 인터페이스는 서로 다른 대상이 상호작용하기 위한 접점과 규칙이다.
• API는 소프트웨어가 다른 소프트웨어의 기능이나 데이터를 사용할 수 있게 하는 프로그래밍 인터페이스다.
• Web API는 API의 한 종류이며, 모든 API가 네트워크 통신을 의미하지는 않는다.
• API 계약에는 주소, 요청 방식, 매개변수, 데이터 형식, 인증, 오류 처리 등이 포함된다.
• API는 내부 구현을 추상화하고 기능의 재사용과 시스템 분리를 돕는다.
• Public API는 외부 개발자에게, Private API는 조직 내부에, Partner API는 특정 협력사에 제공한다.
• 공개 범위와 무관하게 인증, 인가, 호출 제한, 비밀값 관리가 필요하다.
• API는 상호작용 규칙이고 JSON과 XML은 데이터를 표현하는 형식이다.

참고 자료

• 인프런 큰돌님의 CS 지식 강의