[비개발자 사고법 07강] API는 '식당 알바생(점원)'입니다 — 버튼이 작동 안 하는 진짜 이유·REST 5가지·상태 코드 한 방 정리

왜 비개발자가 'API'까지 알아야 할까

"버튼이 작동을 안 해요. 그냥 AI한테 고쳐 달라고 하면 되지 않나요?" 물론 그래도 됩니다. 그런데 그냥 "안 되는데요, 고쳐주세요"라고만 하면, AI도 어디가 문제인지 몰라 엉뚱한 곳을 고치다 끝까지 안 고쳐지는 경우가 생겨요. 비개발자가 코딩을 가장 많이 포기하는 지점이 바로 여기입니다.

그런데 API라는 개념 하나만 잡고 있으면 질문이 완전히 달라집니다. "버튼을 눌렀을 때 알바생(API)이 주문을 실제로 받아서 주방으로 보냈는지 확인해줘", "어느 주문대(주소)로 갔고, 빈손으로(에러로) 돌아왔는지 알려줘"처럼 콕 집어 시킬 수 있죠. 김지백 강사에 따르면, 요즘처럼 코드를 직접 안 짜고 AI에게 시켜 만드는 바이브 코딩 시대엔 이게 특히 큰 무기가 됩니다. 게다가 AI 에이전트가 스스로 도구를 쓰는 것도 사실은 이 API(알바생)를 부르는 것이라, API를 알면 AI에게 일을 제대로 시키는 무기가 하나 더 생깁니다.

🧑‍🍳 API = 화면과 주방 사이를 오가는 '알바생(점원)'

지난 시간에 우리는 손님이 보는 홀(프론트엔드)과 안 보이는 주방(백엔드)을 만났습니다. 그런데 손님이 주방에 직접 들어가서 "이거 해주세요" 할 수 있나요? 아니죠. 그 사이를 알바생(점원)이 오갑니다. 손님이 "비빔밥 하나요!" 하면 알바생이 그 주문을 받아 주방에 전달하고, 완성된 음식을 다시 손님에게 가져다줍니다.

이 화면(손님)과 주방(백엔드) 사이를 오가며 주문을 전달하고 결과를 가져다주는 중개자, 그게 바로 API입니다. 화면은 주방(데이터·서버)에 직접 손댈 수 없어요. 반드시 이 알바생(API)을 통해서만 "이거 가져와", "이거 저장해"를 주고받습니다. 그래서 버튼이 안 될 때 우리는 "알바생(API)에게 주문이 제대로 전달됐나? 주방 어디로 갔나? 빈손으로 왔나?"를 따져볼 수 있는 거죠.

📋 메뉴판 = 알바생에게 시킬 수 있는 '주문 목록'(엔드포인트)

알바생한테 아무거나 막 시킨다고 다 될까요? 아니죠. 메뉴판에 적힌 것만 주문할 수 있습니다. 이렇게 알바생(API)에게 시킬 수 있는 일 하나하나를 어려운 말로 엔드포인트(endpoint)라고 부릅니다. 쉽게 말해 '주문이 가야 할 정확한 주문대(주소)'예요. 메뉴판은 그 주문대들의 목록이고요.

비빔밥을 시키면 알바생이 주문서를 들고 한식 코너로 가야 합니다. 일식 코너로 가면? 당연히 "그런 거 없는데요" 하고 에러가 나죠. 웹도 똑같습니다. 회원가입 버튼을 눌렀으면 회원가입 주문대(/signup)로, 상품을 보려면 상품 주문대(/products)로 알바생이 가야 합니다. 회원가입을 눌렀는데 엉뚱하게 결제 주문대로 가면 화면엔 아무것도 안 나오고 에러만 떠요. 그래서 "이 버튼은 알바생이 어느 주문대로 가야 하지?"를 생각하는 습관이 중요합니다.

🍜 REST API 5가지 동사 — 알바생에게 시키는 '행동'

알바생에게 주문할 땐 "무엇을(주문대)"뿐 아니라 "어떻게 할지(동사)"도 함께 말합니다. 이 "주소 + 동사"로 깔끔하게 주문하는 표준 방식이 바로 REST(레스트)예요. 동사는 더 있지만, 영상에서 강사가 강조한 대표 5가지만 알면 바이브 코딩할 때 훨씬 디테일하게 시킬 수 있습니다.

예를 들어 글을 삭제하는 버튼이 안 먹힐 때를 보죠. 그냥 "이 글 좀 지워줘"라고 하면 AI가 화면에서만 슬쩍 가리고 끝낼 수도 있어요. 그런데 "삭제 버튼을 누르면 DELETE API가 제대로 작동하게 해줘"라고 하면, 알바생이 진짜로 주방에 "취소요"를 전달해 데이터가 지워지게 정확히 작업해 줍니다. 등록인데 GET으로 돼 있으면 "등록이니 POST로 바꿔줘"라고 짚어 줄 수도 있고요.

✉️ 알바생이 든 주문서 — 주문 내용(Body)과 신분 확인(Header)

알바생이 주방에 들고 가는 주문서에는 "돈가스 1개, 비빔냉면 2개"처럼 실제 주문이 적혀 있죠. API 요청의 주문서도 두 칸으로 나뉩니다. 하나는 실제 주문 내용, 다른 하나는 신분·권한 확인이에요.

바디(Body)는 실제 주문 내용입니다. "비빔밥 한 그릇" 같은 알맹이가 여기 들어가요. 보통 JSON(제이슨)이라는 형식으로 담기는데, 비개발자는 몰라도 됩니다. AI가 알아서 잘 짜 주거든요. "아, 진짜 주문 내용이 담기는 칸이구나" 정도만 아시면 돼요.

헤더(Header)는 주문 내용이 아니라 신분·권한을 확인하는 칸입니다. 알바생이 "멤버십 카드 있으세요? 쿠폰 있으세요?"라고 묻는 것처럼, 로그인은 했는지, 권한이 있는지, API 키는 가졌는지를 확인하죠. 그래서 바디(주문 내용)가 완벽해도 헤더가 틀리면 인증이 안 되거나 권한이 없어 알바생이 주문을 거절당합니다.

🚦 알바생이 가져오는 답 — 상태 코드(200·401·403·404·500)

주문을 넣으면 알바생이 결과를 가져다주죠. API도 일을 처리한 뒤 "몇 번으로 처리됐어요" 하고 숫자로 답합니다. 이게 상태 코드(Status Code)예요. 영상에서 강사가 말합니다 — 개발자들은 문제가 생기면 제일 먼저 이 상태 코드부터 본다고요. 다 외울 필요 없고, 대표 다섯 개만 알면 됩니다.

🌮 옆 가게 심부름 — 외부 API와 'API 키' (보안 주의!)

손님이 갑자기 타코를 찾는데, 우리 가게엔 한식·중식·일식·양식밖에 없습니다. 그러자 센스 있는 알바생이 길 건너 타코집에서 사다 주겠다고 하죠. 이게 바로 외부 API(오픈 API)를 가져다 쓰는 것입니다. 내 서비스엔 없는 기능을, 알바생이 남이 잘 차려 둔 가게에 주문해서 받아 오는 거예요. 날씨·지도·결제·번역·ChatGPT 같은 게 전부 이렇게 동작합니다. 내가 직접 날씨를 측정할 필요 없이, 기상청·통계청이 열어 둔 가게에 알바생을 보내 주문만 하면 결과가 오죠.

그런데 옆 가게가 그냥 줄까요? 타코집 직원이 물어봅니다. "본인이 그 가게 직원인 거 증명할 키 있어요?" 이게 바로 API 키입니다. 외부 서비스를 쓰려면 알바생이 "나 이거 쓸 자격 있어요"라는 사용 권한 키(신분증)를 보여줘야 해요. 키가 없으면 401, 권한이 부족하면 403 에러가 납니다.

한눈에 보는 API 7단어 정리

사장님처럼 AI에게 시키는 법 — 증상으로 원인 콕 집기

이제 진짜 써먹을 차례입니다. API 단어를 알면, 버튼이 안 될 때 "어디가 문제인지" AI에게 콕 집어 말할 수 있어요. 그냥 "안 돼요"가 아니라, 증상으로 원인을 짚는 거죠.