API란 프로그램과 프로그램이 데이터를 주고받기 위해 미리 정해 둔 약속이다. 소셜 로그인, 날씨 앱, 결제창처럼 우리가 매일 쓰는 기능 대부분이 이 약속 위에서 돌아간다. 개념 자체는 단순한데, 막상 설명을 읽으면 “앱끼리 연결하는 것”이라는 말만 반복되어 정확히 감이 안 잡히는 경우가 많다.
나는 매일 API를 만들고 연동하는 개발자다. 주변에서 API를 물어볼 때마다 느끼는 건, 정의보다 구조가 먼저 보여야 이해가 빠르다는 점이다. 그래서 이 글에서는 은행 창구 하나로 API의 전체 그림을 그려 본다.
API가 연결하는 건 구체적으로 무엇인가
클라이언트와 서버, 두 주체부터
API를 이해하려면 먼저 등장인물 두 명을 알아야 한다. 클라이언트와 서버다.
클라이언트는 무언가를 요청하는 쪽이다. 스마트폰의 날씨 앱, 웹 브라우저, 또는 다른 서버가 될 수도 있다. 서버는 그 요청을 받아서 처리하고 결과를 돌려주는 쪽이다. 날씨 데이터를 저장하고 있는 기상청 서버가 대표적이다.
중요한 건 클라이언트가 서버 내부에 직접 접근하지 못한다는 점이다. 데이터베이스에 마음대로 들어가서 원하는 정보를 꺼내 오는 구조가 아니다. 반드시 정해진 방식으로 요청해야 하고, 서버가 허용한 범위 안에서만 응답이 온다.
API는 그 사이의 약속이다
API는 Application Programming Interface의 줄임말이다. AWS 공식 문서에서도 설명하듯, 요청과 응답을 사용해 두 애플리케이션이 서로 통신하는 방법을 정의한 계약이다. 핵심은 마지막 단어 Interface, 즉 접점이다. 클라이언트가 서버에 “이런 형식으로 요청하면, 이런 형식으로 답을 줄게”라고 미리 정해 둔 약속 전체를 API라고 부른다.
여기서 많은 사람이 헷갈리는 지점이 있다. API란 프로그램도 아니고, 서버도 아니고, 데이터도 아니다. 두 프로그램 사이에서 “이렇게 말하면 이렇게 대답한다”는 규칙 자체가 API다. 식당 메뉴판이 음식은 아니지만, 메뉴판 없이는 주문할 수 없는 것과 같다.
은행 창구로 보면 한 번에 이해된다
창구 직원이 API다
은행에 가면 금고에 직접 들어가서 돈을 꺼내지 않는다. 창구 직원에게 신청서를 내밀고, 직원이 내부 시스템에서 처리한 뒤 결과를 돌려준다. 이 구조가 API와 정확히 같다.
클라이언트는 고객이다. 서버는 은행 내부 시스템과 금고다. 창구 직원이 곧 API다. 고객이 “잔액 조회요” 하고 정해진 양식에 맞춰 신청하면, 직원이 내부에서 확인하고 “잔액은 50만 원입니다” 하고 돌려준다. 금고가 어디 있는지, 내부 시스템이 어떻게 생겼는지 고객은 알 필요가 없다.
API도 마찬가지다. 서버 내부 구조를 몰라도 API가 정한 형식대로 요청하면 원하는 데이터를 받을 수 있다. 이것이 API의 핵심 가치다. 내부를 몰라도 쓸 수 있게 만드는 것.
신분증이 API 키다
은행 창구에서 신분증 없이 계좌 정보를 달라고 하면 거절당한다. API도 똑같다. 대부분의 API는 API 키라는 고유 식별값을 요구한다. 이 키가 없거나 틀리면 서버는 요청을 거부한다.
API 키는 “이 요청을 보낸 사람이 누구인지, 접근 권한이 있는지” 확인하는 신분증이다. 개발자가 API를 쓰려면 먼저 서비스 제공자에게 키를 발급받아야 한다. 구글 지도 API를 쓰려면 구글에서 키를 받고, 카카오 API를 쓰려면 카카오 개발자 사이트에서 키를 받는 식이다.
헷갈리는 용어 4개, 창구에 대입하면 끝
엔드포인트는 창구 번호
은행에 창구가 여러 개 있듯, API에도 엔드포인트가 여러 개 있다. 엔드포인트는 특정 데이터나 기능에 접근하기 위한 주소(URL)다.
예를 들어 날씨 API라면 https://api.weather.com/current가 현재 날씨를 조회하는 엔드포인트이고, https://api.weather.com/forecast가 주간 예보를 조회하는 엔드포인트다. 1번 창구는 예금, 2번 창구는 대출인 것처럼 각 엔드포인트마다 담당하는 기능이 다르다.
요청과 응답은 신청서와 결과물
클라이언트가 서버에 보내는 것이 요청(request)이고, 서버가 돌려주는 것이 응답(response)이다. 은행 신청서에 계좌번호, 금액, 용도를 적듯이, API 요청에도 필요한 정보를 정해진 형식에 맞춰 담아야 한다.
응답은 대부분 JSON이라는 형식으로 온다. JSON은 데이터를 중괄호와 키-값 쌍으로 표현하는 텍스트 형식이다. 사람이 읽을 수도 있고 프로그램이 처리하기도 쉬워서 API 세계의 공용어처럼 쓰인다.
{
"city": "Seoul",
"temperature": 24,
"condition": "맑음"
}위 JSON은 “서울 기온 24도, 맑음”이라는 응답을 담고 있다. 복잡해 보이지만 구조는 단순하다.
에러 코드는 반송 사유
신청서를 잘못 쓰면 은행 직원이 “이 항목을 다시 확인해 주세요” 하고 안내한다. API도 요청에 문제가 있으면 숫자 코드로 이유를 알려 준다.
에러 코드는 크게 두 묶음이다. 400번대는 요청한 쪽, 즉 클라이언트 문제다. 신청서를 잘못 쓴 셈이다. 500번대는 처리하는 쪽, 즉 서버 문제다. 은행 내부 시스템이 멈춘 상황이다. 이 구분만 알면 에러를 만났을 때 원인이 내 쪽인지 서버 쪽인지 바로 판단할 수 있다.
400번대에서 자주 만나는 코드 세 가지가 있다. 400은 요청 형식 자체가 잘못된 경우다. 필수 항목을 빠뜨리거나 양식에 맞지 않는 값을 보냈을 때 나온다. 401은 인증 실패다. API 키가 없거나 만료됐을 때 받는 코드다. 신분증 없이 창구에 선 셈이다. 404는 요청한 자원이 없는 경우다. 존재하지 않는 창구 번호를 찾아간 것과 같다.
500번대 대표는 500이다. 요청은 정상인데 서버 내부에서 문제가 생긴 경우다. 이때는 기다렸다가 다시 시도하거나, 서비스 제공자 쪽 공지를 확인하는 수밖에 없다.
매일 쓰는 앱 속 API 3가지
소셜 로그인
앱에서 “카카오로 로그인” 버튼을 누르면, 그 앱이 카카오 서버에 API로 사용자 인증을 요청한다. 카카오 로그인은 OAuth 2.0 프로토콜 기반으로 동작하며, 앱은 카카오 비밀번호를 직접 저장하지 않는다(카카오 로그인 이해하기). 카카오 서버가 인증 결과를 토큰으로 돌려주면 로그인이 완료된다.
날씨 앱
스마트폰 날씨 앱은 자체적으로 기상 관측을 하지 않는다. 기상청이나 외부 날씨 서비스의 API에 현재 위치를 보내고, 기온·습도·강수 확률을 JSON으로 받아와서 화면에 보여 준다. 앱을 열 때마다 API 요청이 한 번씩 나간다고 보면 된다.
결제
쇼핑몰에서 결제 버튼을 누르면, 쇼핑몰 서버가 PG(결제 대행) 서버에 API로 결제 요청을 보낸다. PG 서버가 카드사와 통신하고, 승인 결과를 다시 API로 돌려준다. 쇼핑몰이 직접 카드 정보를 처리하는 게 아니라 API를 통해 결제 전문 서비스에 맡기는 것이다. 이 구조 덕분에 작은 쇼핑몰도 복잡한 금융 시스템 없이 결제 기능을 붙일 수 있다.
API란 프로그램 세계의 창구이자 연결 통로이다
API란 프로그램 사이에서 데이터를 주고받기 위한 약속이다. 클라이언트가 정해진 형식으로 요청하면, 서버가 정해진 형식으로 응답한다. 그 사이에 API 키로 신분을 확인하고, 엔드포인트로 목적지를 지정하고, 에러 코드로 문제를 알려 준다.
이 구조는 소셜 로그인이든, 날씨 앱이든, 결제든 전부 같다. 한번 개념이 잡히면 “이 서비스는 API를 공개했다”, “API 호출 횟수 제한이 있다” 같은 표현이 그냥 읽힌다. AI API 동작 원리처럼 더 깊은 주제로 넘어갈 때도 이 기본 구조가 그대로 바탕이 된다.
결국 API란 은행 창구와 같다. 정해진 절차만 따르면 내부를 몰라도 원하는 결과를 받을 수 있다.