서비스끼리 대화하는 창구(API)

쉽게 말하면

API는 영어 줄임말이지만 뜻은 어렵지 않아요. 사람 말고 프로그램끼리 쓰라고 만들어 둔 접수 창구라는 뜻이에요. 사람 손님은 화면의 버튼을 누르지만, 내 서비스는 다른 서비스의 창구에 글자로 된 부탁을 보내요. 손님 눈에는 한 화면이지만, 뒤에서는 결제사와 지도 회사와 문자 회사에 쉴 새 없이 주문 전화가 걸리고 있는 거예요.

손님이 버튼을 누른 뒤 1초 동안

결제를 예로 들면, API 대화 한 번은 이렇게 흘러가요. 이 왕복이 보통 1~2초 안에 끝나요.

1. 1손님이 내 사이트에서 결제하기 버튼을 눌러요. 손님 눈에 보이는 건 여기까지가 전부예요.
2. 2내 서비스가 결제사의 창구(API)에 정해진 양식으로 부탁을 보내요. 누가, 얼마를, 무엇을 사는지요.
3. 3결제사가 카드사와 은행 사이의 복잡한 일을 대신 처리하고, 성공인지 실패인지 답장을 보내요.
4. 4내 화면이 그 답장을 받아서 "결제가 완료됐어요"를 손님에게 보여줘요.

부탁하고, 기다리고, 답을 받는다. API 대화는 이 세 박자가 전부예요. 그런데 여기서 중요한 성질이 하나 나와요. 상대가 답을 안 주면 내 화면도 같이 기다려요. 내 코드가 멀쩡해도 거래처가 멈추면 내 기능이 멈춘다는 뜻이에요. 그래서 API가 낀 기능에는 "내 잘못이 아닌 고장"이 생겨요. 아래에서 그 고장을 알아보는 법을 다뤄요.

내 사이트에 이미 여러 개 들어와 있어요

API는 앞으로 배울 신기술이 아니에요. 사장님 사이트에 이미 여러 개 들어와 있는 것이에요. 남의 기능을 빌린 자리마다 창구가 하나씩 있다고 보면 돼요.

다섯 줄의 공통점이 보이시나요. 전부 정해진 양식, 출입증, 요금표 세 가지가 있어요. 출입증이 바로 API 키예요. 창구는 아무나 받아 주지 않고, 출입증을 보여준 사람의 계정에 요금을 달아 둬요. 그래서 출입증이 새면 남이 쓴 요금이 내 앞으로 쌓여요.

사장님이 실제로 겪는 장면

만들까 빌릴까, 저울에 올려 보면

위 견적 장면의 결정을 표로 펼치면 이래요. 정답이 정해진 문제가 아니라, 내 가게가 지금 어느 단계인지에 따라 답이 달라지는 문제예요.

장사 초반에는 거의 항상 빌리는 쪽이 이겨요. 손님이 올지 안 올지 모르는 기능에 두 달을 쓰는 것보다, 일주일 만에 열어서 반응부터 보는 게 싸거든요. 직접 만들기를 진지하게 고민할 시점은 따로 있어요. 그 기능이 내 가게의 핵심이 됐고, 창구 요금이 매출에서 무시 못 할 몫을 먹기 시작할 때요. 그때는 청구서가 알려 줘요.

증상을 보면 AI에게 할 말이 나와요

API가 낀 고장은 증상이 몇 가지로 정해져 있어요. 왼쪽에서 내 증상을 찾고, 오른쪽 문장을 AI에게 그대로 말하면 돼요. 원인을 사장님이 밝혀낼 필요는 없어요.

지금은 신경 쓰지 않아도 되는 때

가게 소개 페이지, 메뉴판, 포트폴리오처럼 남의 기능을 빌리지 않는 사이트라면 API는 아직 남 얘기예요. 창구를 두드릴 일 자체가 없으니까요. 이 문서를 덮고 만들기에 집중하셔도 돼요. 결제나 예약을 붙이는 날, 그때 다시 펴면 늦지 않아요.

바이브캠퍼스 안에서 만드는 동안에도 이 용어를 외울 필요는 없어요. "카카오맵 넣어줘", "결제 붙여줘"라고 말하면 창구를 두드리는 코드는 AI가 써요. 사장님이 등장할 순간은 딱 두 번이에요. 남의 기능을 빌릴지 결정할 때(요금표를 보는 일), 그리고 그 기능이 멈췄을 때(위 표의 문장을 건네는 일)요.

빌리기 전에, 거래처 보듯 세 가지

API는 대체로 쓴 만큼 내는 요금이에요. 무료 구간을 주는 곳이 많아서 처음엔 0원이다가, 손님이 늘면 청구서가 따라 늘어요. 그래서 붙이기 전에 거래처와 계약하듯 확인할 게 있어요.

1. 1요금표. 무료 한도가 어디까지고, 넘으면 얼마인지. 손님 1,000명 기준으로 한 달에 얼마가 나갈지 어림해 봐요.
2. 2한도. 한꺼번에 얼마나 자주 부탁할 수 있는지. 창구마다 호출 한도가 있어서, 손님이 몰릴 때 여기서 막히면 대목에 문이 닫혀요.
3. 3멈췄을 때. 그쪽이 멈추면 내 가게의 어느 기능까지 같이 멈추는지. 결제처럼 매출과 직결된 창구일수록 대비가 필요해요.

그리고 계약이 끝나면 출입증 관리가 남아요. 창구에서 받은 키는 코드에 적지 않고 환경변수 금고에 넣어요. 키가 새면 남이 내 계정으로 그 창구를 마음껏 써서 요금이 내 앞으로 쌓여요. 자세한 건 API 키 문서에 있어요.

자주 묻는 것

Q. API랑 API 키는 뭐가 달라요?

API는 창구고, 키는 그 창구에 들어가는 출입증이에요. 창구 자체는 누구에게나 공개돼 있지만, 출입증을 보여줘야 일을 해 주고 요금도 그 출입증 주인에게 달아요.

Q. 웹훅이라는 말도 자주 보이던데, 그건 뭐예요?

방향이 반대예요. 내가 필요할 때 물어보는 게 API고, 저쪽에 무슨 일이 생겼을 때 나에게 알려 주는 게 웹훅이에요. 주문 전화와 배달 완료 문자의 관계라고 보면 돼요.

Q. API를 쓰면 무조건 돈이 드나요?

아니요. 무료 구간을 주는 곳이 많아요. 다만 무료의 기준과 초과 요금은 회사마다 달라서, 그 회사의 요금 안내 페이지에서 직접 확인하는 게 정확해요. 손님이 늘면 요금도 는다는 것만 기억하세요.

Q. 빌려 쓰던 회사가 서비스를 접으면 내 사이트는 어떻게 돼요?

그 창구를 쓰던 기능만 멈추고, 사이트 전체가 죽지는 않아요. 같은 일을 하는 다른 거래처로 갈아 끼우면 되는데, 갈아 끼우는 데도 품이 들어요. 그래서 처음부터 오래 갈 만한 큰 곳을 고르는 게 안전해요.

Q. 영어로 된 API 문서를 제가 읽어야 하나요?

아니요. 그건 AI가 읽어요. 사장님은 "이 서비스로 문자 보내는 기능 붙여줘"처럼 원하는 일을 한국어로 말하면 돼요. 사장님이 볼 것은 문서가 아니라 요금표예요.

Q. 무료 한도를 넘겨서 요금이 나가기 시작하면 미리 알 수 있나요?

대부분의 회사가 사용량 그래프와 알림 기능을 제공해요. 가입할 때 사용량 알림부터 켜 두고, 상한을 정할 수 있는 곳이면 상한도 걸어 두세요. 청구서로 처음 알게 되는 게 가장 나쁜 경우예요.

Q. 여러 회사의 창구를 섞어 써도 되나요?

네, 보통 그렇게 해요. 결제는 결제사, 지도는 지도 회사, 문자는 문자 회사. 거래처를 품목마다 따로 두는 것과 같아요. 창구끼리는 서로 몰라도 돼요. 다만 거래처가 늘수록 챙길 청구서와 키도 늘어난다는 것만 기억하세요.

Q. 내 서비스도 API를 만들 수 있나요?

네. 남의 창구를 빌리는 쪽에서, 남에게 창구를 열어 주는 쪽이 될 수도 있어요. 제휴사가 내 데이터를 받아 가게 하는 식이죠. 규모가 커진 뒤의 이야기라, 지금은 그런 방향도 있다는 것만 알면 충분해요.