API가 뭔가요? 분식집 주문지 한 장이면 이해됩니다
한줄 요약: API는 프로그램끼리 데이터를 주고받을 때 쓰는 정해진 주문 양식입니다. 분식집 주문지처럼 “이 주소로, 이런 양식으로 적어 내면, 이런 결과를 돌려준다”가 미리 약속되어 있습니다. 이 글에서는 그 약속이 어떻게 굴러가는지 비유 하나로 꿰고, 마지막에는 브라우저 주소창만으로 실제 API를 직접 호출해 봅니다.
AI에게 “환율 알림 만들어 줘”, “뉴스 요약해서 보내 줘”라고 요청해 본 적이 있다면, 답변 어딘가에서 “API를 연동하면 됩니다”라는 문장을 만났을 겁니다. 개발을 해 본 적이 없다면 여기서 멈추게 됩니다. 검색해 봐도 “애플리케이션 프로그래밍 인터페이스”라는 풀이가 나올 뿐이고, 인터페이스가 뭔지 다시 검색하게 되는 악순환이 시작됩니다.
이 글은 그 악순환을 분식집 주문지 하나로 끊습니다. 읽고 나면 AI가 “API를 연동하면 됩니다”라고 할 때 무엇을 하겠다는 뜻인지 알게 되고, 브라우저로 실제 API를 한 번 호출해 본 상태가 됩니다.
말로 주문하면 어긋나고, 주문지는 어긋나지 않습니다
분식집에 자리를 잡으면 주문지와 펜이 놓여 있습니다. 손님은 정해진 칸에 표시해서 건네고, 주방은 적힌 대로 만들어 내옵니다. 말로 주문을 주고받으면 “덜 맵게요”가 “안 맵게”로 전해지는 일이 생기지만, 양식이 있으면 어긋나지 않습니다.
API가 정확히 이 주문지입니다. 서로 다른 프로그램이 데이터를 주고받으려면 말이 통해야 하는데, 프로그램은 눈치껏 알아듣지 못합니다. 그래서 “이 주소로, 이런 양식으로 요청하면, 이런 데이터를 돌려준다”를 미리 정해 둡니다. 그 약속의 이름이 API(Application Programming Interface)입니다.
분식집에서 일어나는 일 = API 호출에서 일어나는 일
같은 그림을 컴퓨터 과학 교과서식으로 그리면 아래와 같습니다. 위키백과의 클라이언트 서버 문서에 실린 표준 도해인데, 낱말만 영어일 뿐 방금 본 분식집과 같은 그림입니다. client가 손님, request가 주문지 제출, server가 주방, response가 나온 음식입니다.
분식집 용어를 컴퓨터 용어로 바꾸면
주문지 비유는 한 장면으로 끝나지 않습니다. API 문서에서 만나게 될 낯선 단어들이 전부 이 분식집 안에 자리가 있습니다.
| 분식집 | 컴퓨터 용어 | 뜻 |
|---|---|---|
| 손님 | 클라이언트 | 요청하는 쪽 |
| 주방 | 서버 | 요청을 처리해 주는 쪽 |
| 주문지 양식 | API | 요청과 응답의 약속 |
| 주문지 넣는 창구 주소 | 엔드포인트(Endpoint) | 요청을 보내는 인터넷 주소 |
| “오이 빼주세요” | 파라미터(Parameter) | 요청의 세부 옵션 |
| 메뉴 보여주세요 / 주문할게요 | 메서드(GET / POST) | 조회인지 생성인지, 주문 행위의 종류 |
| 나온 음식 | 응답 | 돌아오는 데이터 |
| “나왔습니다” / “그런 메뉴 없습니다” | 상태 코드(200 / 404) | 주방의 대답 |
표의 오른쪽 단어들을 외울 필요는 없습니다. AI가 짜 준 코드나 오류 메시지에서 이 단어를 만났을 때, 왼쪽 칸으로 바꿔 읽을 수 있으면 충분합니다. “404가 떴다”는 “그런 메뉴 없다는 대답이 돌아왔다”이고, “파라미터를 바꿔 보세요”는 “주문 옵션을 바꿔 보세요”입니다.
브라우저 주소창으로 직접 호출해 봅시다
API가 개발자만 만지는 특별한 것이 아니라는 사실은 직접 한 번 호출해 보면 바로 체감됩니다. 준비물은 브라우저뿐입니다. 아래 주소를 주소창에 그대로 붙여 넣어 보세요. Frankfurter라는 무료 환율 API의 창구 주소입니다.
https://api.frankfurter.dev/v1/latest?base=USD&symbols=KRW주소를 뜯어 보면 주문지 그대로입니다. api.frankfurter.dev/v1/latest까지가 주문지를 넣는 창구 주소이고, ? 뒤의 base=USD&symbols=KRW가 주문 옵션입니다. “기준 통화는 미국 달러로, 원화 환율을 보여주세요”라고 적은 셈입니다.
실제로 돌아온 응답 (2026년 8월 28일 기준 실측)
주소 한 줄이 요청이고, 화면에 뜬 글자가 응답입니다. 방금 API를 호출한 겁니다.
이 체험이 중요한 이유가 있습니다. 방금 여러분이 브라우저로 한 일을, 자동화 도구는 매일 아침 대신해 줄 수 있습니다. 같은 주소를 매일 호출해서 응답의 숫자를 읽고, 조건에 맞으면 메일을 보내는 식입니다. AI가 “환율 API를 연동하면 됩니다”라고 말할 때 하겠다는 일이 정확히 이것입니다.
아무나 주문지를 넣을 수는 없습니다
방금 호출한 환율 API는 누구나 쓸 수 있게 열려 있는 경우입니다. 하지만 내 계정의 데이터를 다루는 API는 아무 주문지나 받지 않습니다. 내 Gmail을 읽는 API를 아무나 호출할 수 있다면 큰일이니까요.
그래서 요청할 때 자격을 증명하는 값을 함께 보내는데, 이것이 API 키입니다. 회원카드를 보여줘야 주문을 받아 주는 가게라고 생각하면 됩니다. 서비스에 가입하고 키를 발급받아, 요청에 끼워 보내는 방식입니다.
키를 다루는 순간부터는 보안이 따라옵니다. 회원카드를 남에게 빌려주면 내 이름으로 주문이 쌓이듯, API 키가 새어 나가면 남이 내 계정으로 요청을 보낼 수 있습니다. 키를 발급받고 안전하게 보관하는 실전 요령은 Supabase API 키 고르기 글에서 실제 화면과 함께 다뤘습니다. 참고로 Gmail은 프로그램이 발송 서버에 직접 접속해 메일을 보내는 경우에 한해 앱 비밀번호라는 별도 값을 요구하는데, 언제 필요하고 언제 필요 없는지는 Gmail 앱 비밀번호 발급하기의 경계표에서 확인할 수 있습니다.
더 깊이 읽고 싶다면
이 글은 비유로 뼈대를 잡는 데 집중했습니다. 뼈대가 잡혔다면 아래 두 자료가 살을 붙이기 좋습니다. 둘 다 한국어이고 무료입니다.
- AWS “API란 무엇인가요?” 클라우드 회사가 쓴 표준적인 설명입니다. 날씨 앱이 기상청 데이터를 가져오는 예시로 시작해, API의 종류까지 넓게 다룹니다.
- 토스페이먼츠 개발자센터 “API” 온라인 카드 결제가 일어날 때 뒤에서 API가 어떻게 오가는지를 단계별로 보여줍니다. 실제 서비스의 사례라 체감이 좋습니다.
댓글