웹 API는 무엇인가요?

웹 API란 무엇인가요? JSON이 표준인 이유

웹 API란 무엇인가요? 서로 다른 서비스가 데이터를 교환하는 핵심 연결 구조로, 형식이 맞지 않으면 통신이 이루어지지 않습니다. 특히 데이터 포맷 선택은 속도와 가독성에 직접적인 영향을 줍니다. 기본 개념과 데이터 형식의 차이를 이해하면 웹 서비스 구조가 명확해집니다.

웹 API는 무엇인가요?

웹 API는 식당의 점원(웨이터)과 같습니다. 손님(클라이언트)이 주방(서버)에 직접 들어가 요리를 주문하지 않듯, 우리는 API라는 점원을 통해 원하는 데이터(요리)를 요청하고 받습니다. 기술적으로는 인터넷망(HTTP)을 통해 서로 다른 소프트웨어 프로그램이 대화할 수 있게 해주는 규칙들의 집합입니다.

웹 API는 단순히 데이터를 주고받는 통로가 아니라, 복잡한 내부 로직을 몰라도 기능을 사용할 수 있게 해주는 추상화된 약속입니다. 실제로 전 세계 개발자의 약 70%가 새로운 기능을 직접 만드는 대신 타사 API를 활용해 개발 속도를 높이고 있습니다. 처음부터 바퀴를 다시 발명할 필요가 없기 때문입니다.^[1]

작동 원리: 요청과 응답의 대화

웹 API의 핵심은 요청(Request)과 응답(Response)이라는 단순한 사이클입니다. 클라이언트가 특정 URL(엔드포인트)로 데이터를 달라고 요청하면, 서버는 그에 맞는 데이터를 찾아서 보내줍니다. 복잡해 보이죠? 사실 별거 아닙니다.

데이터의 택배 상자: JSON

이때 데이터는 아무렇게나 주고받지 않습니다. 서로 약속된 형식으로 포장해야 하는데, 현대 웹에서는 주로 JSON(JavaScript Object Notation)이라는 형식을 사용합니다. 과거에는 XML이라는 태그 범벅의 형식을 많이 썼지만, 데이터 크기가 크고 가독성이 떨어져서 지금은 XML 사용률이 20% 미만으로 떨어졌습니다. JSON은 사람도 읽기 쉽고 컴퓨터도 해석하기 쉬워 사실상 업계 표준이 되었습니다.

제가 처음 XML로 된 공공데이터 API를 연동하려다 파싱(해석) 에러만 50번 넘게 냈던 기억이 납니다. 그에 비해 JSON은 자바스크립트 객체와 거의 똑같이 생겨서 다루기가 훨씬 수월했습니다. 이게 왜 중요할까요? 데이터 형식이 가볍수록 모바일 환경에서 로딩 속도가 빨라지기 때문입니다.

웹 API의 세 가지 주요 유형

모든 API가 누구에게나 열려 있는 것은 아닙니다. 접근 권한에 따라 크게 세 가지로 나뉩니다.

1. 퍼블릭 API (Open API)

누구나 제한 없이(혹은 약간의 제한을 두고) 사용할 수 있는 API입니다. 공공데이터포털의 날씨 정보나 구글 맵 API가 대표적입니다. 기업들이 자사 플랫폼 생태계를 확장하기 위해 주로 제공합니다.

2. 프라이빗 API (Private API)

외부에는 철저히 비공개로 유지되며, 기업 내부 시스템끼리 통신할 때만 사용됩니다. 놀랍게도 전체 API 트래픽의 대부분은 이러한 프라이빗 API가 차지합니다.^[3] MSA(마이크로서비스 아키텍처)를 도입한 회사에서는 로그인 서버, 결제 서버, 배송 서버가 서로 이 프라이빗 API로 대화합니다.

3. 파트너 API (Partner API)

특정 비즈니스 파트너에게만 열어주는 전용 통로입니다. 예를 들어, 배달의민족 앱이 식당 POS 기기와 주문 정보를 연동할 때 사용하는 방식입니다. 보안과 계약 관계가 필수적입니다.

가장 많이 쓰이는 아키텍처: REST vs SOAP

API를 만들 때도 건축 양식처럼 정해진 스타일이 있습니다. 가장 흔히 듣게 될 두 가지를 비교해보겠습니다.

API 아키텍처 비교: REST vs SOAP vs GraphQL

어떤 방식을 선택하느냐에 따라 개발 난이도와 성능이 완전히 달라집니다. 현대 웹 개발에서는 REST가 기본이지만, 상황에 따라 다른 선택이 필요할 수 있습니다.

REST API (가장 대중적 ⭐)

필요한 것보다 더 많은 데이터를 받거나(Over-fetching), 여러 번 요청해야 할 수 있습니다

HTTP URL을 통해 자원을 명시하고, 주로 JSON 형식으로 가볍게 데이터를 주고받습니다

구조가 단순하고 배우기 쉬워 웹 API의 70% 이상이 이 방식을 따릅니다

GraphQL (유연한 선택)

초기 학습 곡선이 가파르고 서버 구현이 복잡해질 수 있습니다

클라이언트가 정확히 원하는 필드만 쿼리 언어로 요청하여 받아옵니다

네트워크 요청 횟수를 줄이고 데이터 전송량을 최적화할 수 있습니다

SOAP (구형이지만 강력함)

메시지 구조가 무겁고 개발이 까다로워 모바일 환경에는 부적합합니다

XML 형식을 엄격하게 사용하며 보안 수준이 매우 높습니다

금융권이나 기업용 레거시 시스템에서 높은 보안성과 트랜잭션 관리가 필요할 때 쓰입니다

지훈씨의 쇼핑몰 창업: 결제 연동의 늪에서 탈출하기

서울 마포구에서 의류 쇼핑몰을 준비하던 지훈(29세)씨는 개발 지식이 조금 있어 결제 시스템을 직접 구현해보기로 했습니다. PG사 계약부터 보안 인증까지 혼자 처리하려 했지만, 2주가 지나도 테스트 결제조차 성공하지 못했습니다. 복잡한 암호화 모듈과 액티브X 잔재들이 그를 괴롭혔습니다.

오픈 예정일은 다가오는데 결제창은 오류만 뱉어냈습니다. 지훈씨는 결국 '바퀴를 다시 발명하지 말자'는 격언을 떠올리고, 포트원(구 아임포트)이라는 결제 연동 API를 사용해보기로 했습니다.

처음에는 문서가 영어와 개발 용어로 뒤섞여 있어 당황했지만, '결제 요청'과 '결제 검증'이라는 두 가지 핵심 API만 이해하면 된다는 것을 깨달았습니다. 복잡한 카드사 통신은 API가 대신 처리해주었습니다.

결과적으로 API 도입 단 4시간 만에 카드 결제와 카카오페이 연동을 모두 완료했습니다. 직접 개발하려던 2주의 시간과 스트레스가 무색할 정도로 간단했습니다. 현재 지훈씨의 쇼핑몰은 월 3천 건 이상의 결제를 안정적으로 처리하고 있습니다.