API란? 비개발자 사장님을 위한 기초 가이드

안녕하세요, 3Min API 개발을 이끌고 있는 yeonghyeon입니다.

지난 데이터베이스 편에서 와인샵 사장님의 이야기를 마무리하며 한 가지를 뒤로 미뤄 두었습니다. "온라인몰이 열리고 나면 매장 POS, 웹사이트, 협력 레스토랑에서 들어온 주문이 자동으로 같은 데이터베이스에 쌓인다"고 했는데, 그 "자동으로"라는 말 뒤에 있는 도구가 오늘의 주제입니다. 바로 API입니다.

오늘 글의 목표는 한 가지입니다. API라는 말 뒤의 복잡한 기술을 공부하기 전에, 먼저 "내 비즈니스의 흐름을 머릿속이 아니라 약속된 메시지로 정리하는 감각"을 잡는 것. 이 감각만 잡히면 나머지는 필요할 때 자연스럽게 따라옵니다. 사전지식은 없어도 괜찮습니다.

API란 무엇인가

사전적 정의부터 짧게 보겠습니다. 위키백과는 API(Application Programming Interface)를 "응용 프로그램이 서로 기능이나 데이터를 주고받을 수 있도록 정해진 규칙"이라고 설명합니다.

한 줄로 요약하자면 이렇습니다.

API = 시스템끼리 정해진 규칙으로 데이터를 주고받을 수 있게 만든 창구.

API에도 여러 방식이 있지만, 오늘날 웹에서 가장 널리 쓰이는 것은 REST(또는 RESTful) API입니다. 오늘은 이 REST 방식을 기준으로 이야기하겠습니다. REST 자체의 기술적 세부는 깊이 들어가지 않겠습니다. 비즈니스 관점에서 필요한 것은 "정해진 주소로 정해진 모양의 메시지를 보내면, 정해진 모양의 답이 돌아온다"는 감각 하나면 충분합니다.

짚고 갈 점이 하나 있습니다. API에는 요청에 대한 답이 반드시 돌아옵니다. 그 답은 먼저 성공인지 실패인지를 구분하는 숫자 한 개로 결판난 뒤, 뒤이어 자세한 내용이 따라옵니다. 주문이 제대로 저장되었는지, 아니면 어떤 이유로 거절되었는지가 이 답 안에 담깁니다. 구체적인 모양은 뒤에서 와인샵 이야기와 함께 다시 보겠습니다.

왜 "통로"가 필요할까

은행을 한번 떠올려 보시기 바랍니다. 은행 금고에는 모든 고객의 돈이 들어 있지만, 고객이 금고에 직접 들어가는 일은 없습니다. 대신 창구 직원이 정해진 양식(입출금 전표)으로 요청을 받고, 본인 확인을 거친 뒤 처리해 줍니다. 심지어 창구 직원도 금고에 마음대로 드나들지 않습니다. 규칙과 권한이 정해져 있습니다.

데이터베이스도 똑같은 상황입니다. 기술적으로는 인터넷 너머에서 DB에 바로 접속해 데이터를 읽고 쓰는 일이 가능하지만, 이 문을 모두에게 열어 두는 순간 비즈니스는 무너집니다. 누군가는 전체 고객 목록을 그대로 가져갈 수 있고, 누군가는 상품 가격을 0원으로 바꿀 수 있고, 누군가는 재고 테이블을 통째로 지울 수 있습니다.

그래서 데이터베이스 앞에 API라는 창구를 둡니다. 외부에서 들어오는 요청은 반드시 이 창구를 통과해야 합니다. 창구는 세 가지 일을 합니다. 검증(요청의 형식이 맞는지), 인증·권한 확인(누구이고 무엇을 할 수 있는지), 그리고 정해진 범위의 작업만 수행(고객은 자기 주문만 조회할 수 있고, 가격은 절대 수정할 수 없음). DB가 아니라 API가 외부 세계와 맞닿습니다.

와인샵 사장님의 API

지난 편 마지막 장면을 이어가 보겠습니다. 와인샵 사장님은 온라인몰을 열었고, 매장 POS와 웹사이트, 협력 레스토랑이 동시에 같은 데이터베이스를 바라봅니다. 이 그림이 성립하는 이유는 단 하나, 각자가 API를 통해서만 DB에 접근하기 때문입니다.

세 주체가 보내는 요청을 자연어로 옮겨 보면 이렇게 생겼습니다.

• 매장 POS → "주문 한 건을 저장해 주세요." (새로 쓰기)
• 쇼핑몰 → "Alex가 지난달에 산 와인 목록을 알려주세요." (읽기)
• 협력 레스토랑 → "Château Margaux 2020의 재고를 10병 차감해 주세요." (수정)

각 요청은 정해진 주소(URL)로, 정해진 모양의 메시지에 담겨 들어옵니다. 메시지 자체는 대개 JSON이라는 형식으로 묶인 한 덩어리입니다. JSON이라는 말이 낯설다면, 채원씨가 먼저 쓴 데이터에도 계획이 필요하다를 잠깐 훑어보셔도 좋습니다. 오늘은 "데이터 한 덩어리를 규격대로 담아 보내는 봉투" 정도로만 이해하시면 충분합니다.

이렇게 주소와 메시지 모양을 미리 맞춰 두면, 와인샵 사장님이 주무시는 동안에도 주문은 자동으로 들어오고, DB에는 같은 모양으로 차곡차곡 쌓입니다. 매장 직원이 수기로 옮겨 적지 않아도, 쇼핑몰 관리자가 엑셀을 합치지 않아도 됩니다. 규칙이 만들어졌기 때문에 자동화가 가능해진 것입니다.

그럼 창구가 요청을 받은 뒤에는 어떻게 될까요. 반드시 답이 돌아옵니다. 이 답은 사람이 읽는 문장이 아니라 숫자 한 개로 먼저 결판납니다. HTTP 상태 코드라고 부르는 이 숫자는 수십 종이 있지만, 비즈니스 오너는 세 덩어리만 아시면 충분합니다.

• 200번대 — 성공: 요청이 정상적으로 처리되었습니다. 주문이 저장되었거나, 조회한 데이터가 함께 돌아옵니다. (예: 200 OK, 201 Created)
• 400번대 — 요청이 잘못됨: 보낸 메시지 쪽에 문제가 있습니다. 필수 항목이 빠졌거나, 권한이 없거나, 그런 주소가 존재하지 않는 경우입니다. (예: 400 Bad Request, 401 Unauthorized, 404 Not Found)
• 500번대 — 서버 쪽 문제: 창구 안쪽에서 이상이 생긴 경우입니다. 내 요청이 맞아도 실패할 수 있으므로, 잠시 뒤 다시 시도하도록 설계합니다. (예: 500 Internal Server Error)

숫자 뒤에는 보통 JSON 한 덩어리가 함께 따라옵니다. 성공이면 저장된 주문의 ID가, 실패면 무엇이 왜 틀렸는지가 담깁니다. 와인샵 API에 "수량 필드가 빠진 주문"을 보내면 창구는 400과 함께 "quantity 필드가 필요합니다" 같은 메시지를 되돌려 줍니다. 이 약속 덕분에 시스템끼리도, 사람과 시스템도, 같은 언어로 성공과 실패를 구분할 수 있습니다.

API는 사실 어디에나 있습니다

와인샵 이야기가 아니더라도, 오늘 하루 여러분이 쓴 앱들은 대부분 뒤에서 누군가의 API를 부르고 있었습니다. 인스타그램 앱이 피드를 채워 주는 것도 서버의 DB를 API로 읽어오는 일입니다. 테슬라 운전자가 모바일 앱으로 차량 상태를 확인하는 것, 날씨 앱이 오늘 비 소식을 보여주는 것, 배달 앱이 가게 메뉴를 보여주는 것 모두 마찬가지입니다. 최근에는 냉장고의 주문 버튼, 자동차의 음성 비서, 스마트 스피커까지 API 위에서 돌아갑니다.

지금까지 이야기한 API는 "내가 필요할 때 상대 창구를 찾아가 요청을 보내는" 방식이었습니다. 반대로 상대 시스템이 먼저 내 창구로 찾아와 "방금 이런 일이 생겼습니다"라고 알려주는 방식도 필요합니다. 결제가 완료되었을 때 결제사가 내 서버로 알림을 밀어 주는 장면이 대표적입니다. 이 방식을 따로 웹훅이라 부릅니다.

사실 API와 웹훅은 기술적으로 완전히 같은 것입니다. 요청 주소도, 메시지 모양도, 인증 방식도, 응답 코드도 — 어느 하나 다르지 않습니다. 같은 HTTP 창구 위에서 JSON 한 덩어리를 주고받는 같은 도구이며, 호출하는 코드도 거의 구분이 가지 않습니다. 그런데 왜 다르게 부를까요. 초창기 웹 API는 대부분 "내가 필요할 때 상대에게 요청해 받아 오는" 용도로 설계됐는데, 시간이 지나면서 "사건이 생기면 상대가 먼저 알려 주는" 반대 방향 호출이 점점 많아졌습니다. 이 반대 방향을 구분해 부르기 위해 2007년경 웹훅(Webhook)이라는 이름이 새로 붙었습니다. 기술이 둘로 갈라진 게 아니라, 같은 도구에 역할 이름이 하나 더 생긴 것입니다.

그러니 이렇게만 기억하시면 됩니다. 내가 먼저 부르면 API, 상대가 먼저 부르면 웹훅.

그럼 API는 어떻게 만들까

여기까지 읽으시면 "그래서 내 비즈니스에도 API 하나 만들면 되겠네"라는 생각이 자연스럽게 드실 수 있습니다. 그런데 실제로 API 하나를 "24시간 365일 안전하게 돌아가게" 만들려면 생각보다 많은 조각이 필요합니다. 솔직하게 나열해 보겠습니다.

• 고유 주소: 인터넷에서 부를 수 있어야 하니 도메인을 사고, DNS를 설정하고, HTTPS 인증서를 붙여야 합니다.
• 24/7 라이브 서버: 한 대라도 꺼지면 매출이 멈춥니다. 서버를 여러 대 두고, 장애를 감지하고, 자동으로 살려주는 장치가 필요합니다.
• 코드: 요청을 받아 검증하고, 에러를 구분하고, 응답을 정해진 모양으로 돌려주고, 기록을 남기는 코드를 직접 작성합니다.
• 인증·권한: 누가 어떤 API를 부를 수 있는지 구분해야 합니다. API 키를 발급하고, 만료시키고, 도난당한 키를 비활성화하는 운영도 계속됩니다.
• 데이터베이스 연동: DB는 별도로 설치·운영해야 합니다. 백업, 보안, 성능 관리가 API와 별개로 돌아갑니다.
• 스케일링·모니터링: 이벤트 시즌에 트래픽이 튀면 자동으로 늘어나야 하고, 평소에는 비용을 줄이기 위해 줄어야 합니다. 에러율·응답 속도·비용을 실시간으로 지켜보는 대시보드도 필요합니다.

이 모든 조각을 혼자서 만들어야 하는 것은 아닙니다. AWS, Google Cloud, Cloudflare, Firebase, Supabase 같은 클라우드 플랫폼이 각 조각을 제공합니다. 다만 조각을 고르고 엮고 운영하는 일 자체가 전문 영역입니다. 비즈니스 오너가 직접 처음부터 구축한다면, 보통 백엔드 개발자 한 명의 몇 주에서 몇 달이 드는 작업입니다.

지금까지의 정리

짧게 다시 묶겠습니다.

• API는 데이터베이스에 안전하게 접근할 수 있게 해주는 창구입니다.
• 창구는 정해진 주소와 정해진 모양의 메시지로만 요청을 받습니다.
• 이 약속이 있기 때문에 여러 시스템이 동시에 같은 데이터를 바라보며 움직일 수 있습니다.
• 여러분이 주무시는 동안에도 API는 호출되고, 필요한 쪽에서 다른 API를 호출합니다. 자동화의 실체는 이 약속 위에 있습니다.

오늘 바로 해볼 수 있는 것

지난 데이터베이스 편에서는 엑셀 세 장으로 비즈니스의 데이터 구조를 그려 보았습니다. 오늘은 그 데이터가 오가는 "통로"를 한 번 상상해 보겠습니다. 전부 머리와 AI만 있으면 되며, 코드도, 서버도, 결제도 필요하지 않습니다.

Action 1. 내 비즈니스의 엔드포인트 한 개 그려보기

지난 편에서 나누어 본 "사람 / 물건 / 거래" 시트 중 하나를 고르고, "이 시트에 한 줄이 새로 들어오는 사건"을 정의해 보시기 바랍니다. 예: "온라인몰에서 신규 주문이 들어왔을 때". 종이 위에 단 세 줄만 적으시면 됩니다.

1. 사건 이름: 예) 주문 생성
2. 누가 보내는가: 예) 쇼핑몰, 매장 POS, 고객 문의 폼
3. 어떤 데이터가 담기는가: 예) 고객 번호, 상품 번호, 수량, 금액

이 세 줄이 바로 엔드포인트 한 개의 설계입니다. 개발자가 API를 만들 때 가장 먼저 그리는 그림도 이 수준의 메모에서 시작합니다.

Action 2. AI에게 전체 계획 받기

Action 1에서 적은 메모와 함께 아래 프롬프트를 ChatGPT, Claude, Gemini 중 아무거나 열어 붙여 넣어 보시기 바랍니다.

다음 서비스 문서를 참고해서, 제가 앞서 정리한 엔드포인트를 실제로 구현하려면
어떤 순서로 시작하면 좋을지 비개발자가 이해할 수 있는 말로 단계별로 알려주세요.

https://3minapi.com/llms-full.txt

AI가 돌려줄 답은 대체로 "엔드포인트 하나를 만들고, 주문 한 건을 JSON 한 덩어리로 보내라"는 방향일 것입니다. 용어가 조금 낯설어도 당황하지 마시기 바랍니다. 오늘 배운 "창구" 하나를 여는 일이라는 것만 기억하시면 됩니다.

Action 3. 3분 만에 첫 API 직접 체험해 보기

직접 도메인을 사고 서버를 띄우고 DB를 설치하는 코스는 오늘 단계에서는 과합니다. 아래 퀵스타트 가이드를 따라가시면 데이터베이스 생성 → API 엔드포인트 생성 → 호출 → DB 저장 확인까지의 전체 흐름을 3분 안에 손으로 밟아보실 수 있습니다.

여기서 한 가지 의문이 드실 수 있습니다. "API는 만들었는데, 데이터베이스는 언제 만드나요?" 앞서 말씀드린 대로 원래는 DB를 별도로 설치·운영해야 하지만, 3Min API에서는 엔드포인트를 만들 때 담을 데이터의 모양(필드)을 정의하면, 그에 맞는 저장 공간이 뒤에서 자동으로 함께 만들어집니다. 창구(API)만 설계하시면 금고(DB)는 함께 마련되는 셈입니다. '3분'이라는 이름을 쓸 수 있는 이유가 여기에 있습니다.

👉 개발자 없이 엔드포인트 만들기 — 퀵스타트 가이드

다음 편으로

지난 편에서 데이터를 담는 그릇을 보았고, 오늘 그 그릇과 바깥 세상을 잇는 통로를 보았습니다. 여기까지 오시면 남은 질문은 하나입니다. "그릇 사이를 오가는 메시지는 정확히 어떻게 생겼나요?"

다음 편에서 그 메시지의 모양, 즉 JSON을 다루겠습니다. 와인샵 주문 한 건이 어떤 봉투에 담겨 POS에서 서버로, 서버에서 쇼핑몰로 건너가는지 이어서 따라가 보시기 바랍니다.

---

← 이전 편: 데이터베이스란? 엑셀 쓰던 사장님의 기초 가이드
→ 다음 편: JSON이란? 비개발자 사장님을 위한 기초 가이드