API는 프로그램 사이의 약속이다
앱이나 웹 서비스를 쓰다 보면 한 서비스 안에서 여러 기능이 자연스럽게 이어진다. 쇼핑몰 앱에서 카카오나 구글 계정으로 로그인하고, 카드로 결제하고, 배송 위치를 확인한다. 겉으로는 한 앱 안에서 모두 처리되는 것처럼 보이지만 실제로는 여러 회사와 시스템이 서로 정보를 주고받는다.
이때 필요한 것이 API다. API는 Application Programming Interface의 줄임말이다. 어렵게 들리지만 핵심은 단순하다. 서로 다른 프로그램이 정해진 방식으로 요청하고 응답하기 위한 약속이다.
앞 장에서 서버는 사용자의 요청을 받아 처리하고 응답한다고 했다. API는 그 요청과 응답의 형식을 더 분명하게 정해 놓은 규칙이라고 볼 수 있다. 어떤 주소로 요청해야 하는지, 어떤 정보를 함께 보내야 하는지, 성공하면 어떤 결과가 오는지, 실패하면 어떤 오류가 오는지를 미리 정리해 둔다.
예를 들어 지도 서비스가 "주소를 보내면 위도와 경도를 돌려주겠다"는 API를 제공할 수 있다. 결제 회사는 "결제 금액과 주문 정보를 보내면 승인 여부를 알려주겠다"는 API를 제공할 수 있다. 배송 회사는 "운송장 번호를 보내면 현재 배송 상태를 알려주겠다"는 API를 제공할 수 있다.
API를 이해하면 현대 서비스가 혼자 모든 기능을 만드는 것이 아니라, 필요한 기능을 다른 서비스와 연결해 완성된다는 점을 볼 수 있다.
AI 생성 이미지
API를 식당 메뉴판처럼 생각하기
API를 가장 쉽게 이해하는 방법은 식당 메뉴판에 비유하는 것이다.
식당에 가면 손님은 주방에 들어가 재료를 고르고 조리 과정을 직접 지시하지 않는다. 대신 메뉴판을 보고 주문한다. 메뉴판에는 주문할 수 있는 음식 이름, 가격, 선택 가능한 옵션이 적혀 있다. 손님은 정해진 방식으로 주문하고, 주방은 그 주문을 받아 음식을 만든 뒤 내준다.
API도 비슷하다. 서비스를 이용하는 프로그램은 상대 서비스의 내부 구조를 알 필요가 없다. "회원 정보 조회", "결제 승인 요청", "날씨 정보 조회"처럼 API가 허용한 기능을 정해진 형식대로 요청하면 된다. 상대 서비스는 내부에서 필요한 처리를 한 뒤 결과를 응답한다.
여기서 중요한 점은 메뉴판에 없는 음식을 마음대로 주문할 수 없다는 것이다. API도 마찬가지다. 제공자가 열어 둔 기능만 사용할 수 있다. 또 "아무렇게나 말해도 알아듣는" 방식이 아니다. 주문 형식이 맞아야 한다. 도시 이름을 보내야 하는 API에 상품 번호를 보내면 올바른 결과를 받을 수 없다.
API는 내부를 모두 공개하는 문이 아니다. 오히려 필요한 기능만 안전하게 열어 두는 창구에 가깝다. 식당 주방이 손님에게 모든 조리 도구와 재료 창고를 공개하지 않는 것처럼, 서비스도 데이터베이스 전체를 외부에 열지 않는다. 대신 필요한 기능을 제한된 방식으로 제공한다.
날씨 앱은 어떻게 기상 데이터를 받아올까
날씨 앱을 예로 들어 보자. 사용자가 앱을 열면 화면에는 현재 기온, 강수 확률, 미세먼지, 주간 예보가 표시된다. 하지만 날씨 앱 회사가 전국에 직접 관측 장비를 설치해 모든 기상 데이터를 수집하는 것은 아닐 수 있다. 대신 기상 데이터를 제공하는 기관이나 회사의 API를 사용할 수 있다.
흐름은 대략 다음과 같다.
사용자가 날씨 앱을 연다.
앱은 사용자의 현재 위치나 선택한 도시를 확인한다.
앱 또는 앱의 서버가 기상 데이터 API에 요청을 보낸다.
요청에는 도시, 날짜, 필요한 정보 종류, 인증 정보 등이 포함된다.
기상 데이터 서비스는 요청을 확인하고 결과를 응답한다.
앱은 받은 데이터를 사람이 보기 쉬운 화면으로 바꿔 보여 준다.
응답은 보통 사람이 읽는 문장보다 컴퓨터가 처리하기 쉬운 데이터 형태로 온다. 예를 들어 "서울의 현재 기온은 24도이고 강수 확률은 30%입니다"라는 문장 대신, 지역: 서울, 기온: 24, 강수확률: 30처럼 항목별로 나뉜 데이터가 올 수 있다. 개발에서는 이런 데이터를 JSON 같은 형식으로 주고받는 경우가 많다. JSON은 데이터를 이름표가 붙은 상자처럼 정리해 전달하는 형식이라고 생각하면 된다.
중요한 것은 API가 화면을 그대로 가져오는 것이 아니라는 점이다. 날씨 API는 보통 예쁜 날씨 화면을 보내 주지 않는다. 기온, 습도, 강수 확률 같은 재료를 보내 준다. 그 재료를 어떻게 배치하고 어떤 아이콘을 보여 줄지는 앱이 결정한다.
소셜 로그인, 결제, 배송 조회도 API로 연결된다
API는 날씨처럼 정보를 가져오는 데만 쓰이지 않는다. 우리가 자주 쓰는 기능 대부분이 API와 연결되어 있다.
소셜 로그인을 생각해 보자. 어떤 서비스에서 "구글로 로그인" 또는 "카카오로 로그인" 버튼을 누르면, 해당 서비스는 구글이나 카카오의 API를 통해 사용자의 신원을 확인한다. 이때 중요한 점은 새 서비스가 사용자의 구글 비밀번호나 카카오 비밀번호를 직접 받아 저장하는 것이 아니라는 점이다. 사용자는 원래 계정 제공자에게 로그인하고, 계정 제공자는 "이 사용자는 확인된 사용자다"라는 결과를 정해진 방식으로 돌려준다. 서비스는 그 결과를 바탕으로 회원가입이나 로그인을 진행한다.
카드 결제도 비슷하다. 쇼핑몰이 모든 카드사의 결제 시스템을 직접 운영하지는 않는다. 결제 대행사나 카드사의 API와 연결해 결제 승인을 요청한다. 쇼핑몰은 주문 번호, 결제 금액, 상품 정보 같은 필요한 정보를 보낸다. 결제 시스템은 카드 유효성, 한도, 보안 절차 등을 확인한 뒤 승인 또는 실패 결과를 돌려준다. 쇼핑몰은 그 응답에 따라 주문 상태를 "결제 완료"로 바꾸거나 사용자에게 실패 사유를 안내한다.
배송 조회도 API의 대표적인 사례다. 쇼핑몰은 택배사의 모든 물류 시스템을 직접 갖고 있지 않다. 대신 운송장 번호를 택배사 API에 보내고, 택배사는 현재 위치나 배송 단계를 응답한다. 사용자는 쇼핑몰 앱 안에서 배송 정보를 보지만, 그 정보의 출처는 외부 택배 시스템일 수 있다.
이처럼 API는 서비스들이 서로 역할을 나누게 해 준다. 한 회사가 지도, 결제, 로그인, 문자 발송, 배송, 번역 기능을 모두 처음부터 만들 필요는 없다. 잘 운영되는 외부 기능과 연결해 더 빠르게 서비스를 만들 수 있다.
API 문서는 사용 설명서다
API를 사용하려면 제공자가 정한 규칙을 알아야 한다. 이 규칙을 정리한 것이 API 문서다. API 문서는 제품 설명서나 조립 설명서와 비슷하다.
API 문서에는 보통 다음과 같은 내용이 들어 있다.
어떤 기능을 사용할 수 있는지
요청을 보낼 주소는 무엇인지
어떤 정보를 필수로 보내야 하는지
선택해서 보낼 수 있는 정보는 무엇인지
성공했을 때 어떤 응답이 오는지
실패했을 때 어떤 오류가 오는지
하루 또는 1분에 몇 번까지 호출할 수 있는지
여기서 호출은 API에 요청을 보내는 일을 뜻한다. 전화 한 통을 거는 것처럼, 프로그램이 API에 한 번 요청을 보내면 "API를 한 번 호출했다"고 말한다.
API 문서가 중요한 이유는 작은 차이로도 연결이 실패할 수 있기 때문이다. 예를 들어 날짜 형식을 2026-06-11로 보내야 하는데 2026년 6월 11일로 보내면 상대 시스템이 이해하지 못할 수 있다. 금액을 원 단위 숫자로 보내야 하는데 쉼표가 포함된 문자열로 보내도 오류가 날 수 있다.
사람끼리는 "대충 이런 뜻이겠지" 하고 이해할 수 있지만, 프로그램끼리는 약속된 형식이 맞아야 한다. API 문서는 그 약속을 확인하는 기준이다.
인증키는 출입증과 같다
많은 API는 아무나 사용할 수 없게 되어 있다. 그래서 인증키를 요구한다. 인증키는 API를 사용할 자격이 있는지 확인하는 일종의 출입증이다.
회사 건물에 들어갈 때 출입카드를 찍는다고 생각해 보자. 출입카드가 있어야 누가 들어왔는지 알 수 있고, 허용된 구역만 들어가게 할 수 있다. API 인증키도 비슷하다. API 제공자는 인증키를 통해 어떤 서비스가 요청했는지 확인하고, 사용량을 계산하며, 문제가 생겼을 때 차단할 수 있다.
인증키는 비밀번호처럼 조심해서 다루어야 한다. 인증키가 외부에 노출되면 다른 사람이 내 서비스 이름으로 API를 사용할 수 있다. 유료 API라면 비용이 발생할 수 있고, 악의적인 요청 때문에 서비스가 차단될 수도 있다. 그래서 실제 개발에서는 인증키를 사용자 앱 안에 그대로 넣지 않고 서버에서 안전하게 관리하는 경우가 많다.
호출 제한은 왜 필요할까
API에는 호출 제한이 있는 경우가 많다. 예를 들어 1분에 100번, 하루에 10만 번처럼 사용 가능한 횟수를 정해 둔다. 처음 들으면 불편해 보일 수 있지만, 호출 제한은 서비스 운영에 꼭 필요하다.
식당에 손님이 한꺼번에 몰리면 주방이 감당하지 못한다. 그래서 예약을 받거나, 대기표를 나누거나, 한 번에 주문할 수 있는 양을 제한하기도 한다. API도 마찬가지다. 너무 많은 요청이 한순간에 몰리면 제공자의 서버가 느려지거나 멈출 수 있다. 호출 제한은 전체 사용자가 안정적으로 API를 쓰게 하기 위한 장치다.
호출 제한은 비용 관리와도 연결된다. 외부 API는 무료처럼 보여도 실제로는 서버 운영비와 데이터 처리 비용이 든다. 지도, 문자 발송, 결제, 번역, 인공지능 API처럼 사용량에 따라 비용이 늘어나는 서비스도 많다. 개발 프로젝트에서 API 사용량을 예상하지 않으면 서비스가 인기를 얻을수록 비용이 갑자기 커질 수 있다.
그래서 운영 중인 서비스는 API 호출 횟수, 실패율, 응답 속도, 비용을 꾸준히 확인해야 한다. 기능이 잘 연결되었는지만 보는 것이 아니라, 오래 안정적으로 쓸 수 있는지도 함께 봐야 한다.
API를 이해할 때 오해하기 쉬운 점
첫째, API는 데이터베이스를 그대로 열어 주는 것이 아니다. 외부 서비스가 필요한 기능만 사용할 수 있도록 정리한 통로다. 그래서 API를 쓴다고 해서 상대 서비스의 모든 데이터를 볼 수 있는 것은 아니다.
둘째, API 연결은 한 번 붙이면 끝나는 일이 아니다. 외부 서비스의 정책이 바뀌거나, 응답 형식이 바뀌거나, 장애가 발생할 수 있다. API 제공자가 새 버전을 내면 기존 연결을 수정해야 할 수도 있다. 그래서 중요한 기능일수록 오류 상황을 대비해야 한다.
셋째, API를 쓰면 개발이 무조건 쉬워지는 것은 아니다. 직접 만들지 않아도 되는 장점은 크지만, 외부 서비스의 규칙과 비용, 장애 가능성에 영향을 받는다. 결제 API가 느려지면 쇼핑몰 결제도 지연될 수 있다. 배송 API가 응답하지 않으면 배송 조회 화면도 제대로 표시되지 않을 수 있다.
넷째, API는 화면이 아니라 기능과 데이터의 약속이다. 지도 API를 쓴다고 해서 우리 서비스에 자동으로 좋은 사용자 경험이 생기는 것은 아니다. 어떤 시점에 지도를 보여 줄지, 오류가 나면 어떻게 안내할지, 사용자의 위치 정보를 어떻게 보호할지는 여전히 우리 서비스가 설계해야 한다.
API는 현대 개발에서 서비스들을 이어 주는 기본 언어에 가깝다. 로그인은 계정 서비스와, 결제는 금융 시스템과, 배송은 물류 시스템과, 지도는 위치 서비스와 대화한다. 이 대화가 잘 설계되어야 사용자는 하나의 자연스러운 서비스처럼 느낀다.
결국 API를 안다는 것은 "이 기능을 직접 만들 것인가, 외부 서비스와 연결할 것인가", "어떤 데이터를 주고받아야 하는가", "오류와 비용은 어떻게 관리할 것인가"를 판단할 수 있다는 뜻이다. 개발 지식이 없는 사람에게도 API 이해가 중요한 이유가 여기에 있다.
이 노트는 보도·비평·교육·연구 목적으로 작성되었습니다. 저작권 문의가 있으시면 에서 알려주세요.