API란? 앱 빌더를 위한 쉬운 설명

API(응용 프로그램 인터페이스)는 한 소프트웨어가 다른 소프트웨어에 데이터를 요청하거나 어떤 동작을 시키기 위해 정해 둔 방식입니다. 앱은 합의된 형식으로 요청을 보냅니다. "내일 예약 목록을 줘", "이 카드에 €20 청구해 줘", "이 글을 요약해 줘" 같은 요청이며, 상대 시스템은 구조화된 응답을 돌려줍니다. API는 앱의 여러 부분이 서로 대화하는 방식이며, 앱이 결제, 이메일, 지도, AI 같은 외부 서비스를 사용하는 방식이기도 합니다.

AI로 만들 때 API가 중요한 이유

거의 모든 쓸모 있는 앱은 API를 통해 소통하는 부품으로 이루어져 있습니다.

• 앱 안에서는, 브라우저의 화면이 여러분의 백엔드 API를 호출해서 데이터를 불러오고 저장합니다.
• 앱 밖에서는, 백엔드가 다른 회사의 API를 호출합니다. 결제를 받으려면 Stripe를, 영수증을 보내려면 이메일 제공업체를, 텍스트를 생성하려면 AI 모델 제공업체를 호출합니다.

AI 빌더에게 "결제를 받아 줘" 또는 "AI 요약을 추가해 줘"라고 요청하면, 실제로 AI가 하는 일은 API를 호출하는 코드를 작성하는 것입니다. 기본을 알아 두면 AI가 여러분에게 무엇을 필요로 하는지(보통 해당 서비스의 계정과 API 키), 어디서 문제가 생길 수 있는지, 비용이 얼마나 드는지 이해하기 쉬워집니다.

일상적인 비유

식당을 떠올려 보세요. 주방에 들어가서 직접 요리하지는 않습니다. 메뉴를 읽고, 주방이 이해할 수 있는 방식으로 웨이터에게 주문하면, 웨이터가 음식을 가져다줍니다. 또는 그 요리가 품절이라고 알려 줍니다.

• 메뉴는 API 문서입니다. 무엇을 요청할 수 있고 어떻게 하는지 적혀 있는 목록입니다.
• 웨이터는 API입니다. 요청이 들어오고 응답이 나가는 정해진 한 가지 방식입니다.
• 주방은 다른 시스템입니다. 내부가 어떻게 작동하는지 알 필요가 없습니다.
• 주문은 요청이고, 접시에 담긴 음식은 응답입니다.

메뉴만 같다면 주방은 오븐과 직원을 바꿔도 여러분에게 영향이 없습니다. 이것이 API의 진짜 가치입니다. 두 시스템이 서로 어떻게 만들어졌는지 몰라도 함께 일할 수 있게 해 줍니다.

웹 API 요청이 작동하는 방식

여러분이 만나게 될 대부분의 API는 브라우저가 쓰는 것과 같은 프로토콜인 HTTP로 작동하는 웹 API입니다. 각 요청에는 몇 가지 부분이 있습니다.

그리고 각 응답에는 다음이 있습니다.

JSON(JavaScript Object Notation)은 중괄호 안에 이름과 값을 적는 간단한 텍스트 형식입니다. 웹 API가 데이터를 주고받는 표준 방식입니다.

REST: 가장 흔한 방식

REST는 웹 API를 설계할 때 널리 쓰이는 관례입니다. 각 종류의 대상마다 고유한 URL이 있고, 표준 메서드가 그 대상에 무엇을 하는지 나타냅니다. 예약 앱의 REST API는 다음과 같을 수 있습니다.

PUT도 있으며, 관례적으로 레코드 전체를 대체합니다. 반면 PATCH는 보낸 필드만 바꿉니다.

가장 자주 보게 될 상태 코드는 다음과 같습니다.

앱이 고장 나면 상태 코드가 가장 빠른 단서일 때가 많습니다. 결제 제공업체에서 401이 나오면 보통 API 키가 없거나 틀렸다는 뜻이고, 429는 너무 자주 호출하고 있다는 뜻입니다.

REST만 있는 것은 아닙니다. GraphQL이나 RPC 방식의 API도 있지만, 대부분의 서비스와 AI로 만든 백엔드가 쓰는 것은 REST입니다.

실제 예: 예약 확인

고객이 미용실 앱에서 머리 예약을 하면, 1~2초 사이에 여러 API 호출이 일어날 수 있습니다.

1. 브라우저의 예약 페이지가 서비스, 시간, 고객 정보를 담아 백엔드에 POST /api/bookings를 보냅니다.
2. 백엔드가 그 시간대가 비어 있는지 확인하고, 예약을 데이터베이스에 저장한 뒤 201 Created를 반환합니다.
3. 백엔드가 비밀 키를 담아 이메일 제공업체의 API를 호출합니다. "이 확인 메일을 lena@example.com에게 보내 줘."
4. 선결제가 있다면, 백엔드가 결제 제공업체의 API에 결제 세션을 만들어 달라고 요청하고 고객을 그리로 보냅니다.
5. 나중에 결제 제공업체가 여러분의 앱을 호출해서 결제가 성공했다고 알립니다. 이 역방향 호출이 웹훅입니다.

처음 두 단계는 프론트엔드와 백엔드 사이의 여러분 자신의 API입니다. 3~5단계는 제3자 API입니다.

자주 쓰는 용어 설명

흔한 실수와 오해

• 프런트엔드에 비밀 키 넣기. 브라우저에서 실행되는 코드에 있는 것은 방문하는 누구든 볼 수 있습니다. 비밀 키는 서버에, 환경 변수나 시크릿에 남아 있어야 합니다.
• 채팅에 키 붙여 넣기. 채팅 기록이 저장될 수 있습니다. 대신 빌더의 시크릿 기능을 쓰고, 노출된 키는 모두 교체하세요.
• API가 무료라고 가정하기. 많은 API는 요청마다, 또는 사용량 단위로 요금을 받습니다. AI 모델 API는 토큰 단위로 과금합니다. 요금을 확인하고 지출 한도를 설정하세요. LLM API 사용법을 참고하세요.
• 실패를 처리하지 않기. 외부 서비스는 다운되고, 시간 초과되고, 한도에 걸립니다. 적절한 오류 메시지와 재시도를 요청하세요.
• 브라우저를 신뢰하기. 여러분 자신의 API도 권한을 직접 확인해야 합니다. 버튼을 숨긴다고 누군가 엔드포인트를 직접 호출하는 것을 막을 수는 없습니다.
• 테스트하면서 실제 키 쓰기. 출시 준비가 될 때까지는 테스트 모드 키를 쓰세요.

AI 빌더에게 무엇을 요청할까요

• "이 앱은 어떤 외부 API를 쓰고, 각각 비용이 얼마인지 알려 줘."
• "결제 API는 서버에서만 호출해 줘. 키는 환경 변수에서 읽어 줘."
• "우리 API의 모든 엔드포인트를, 각각 무엇을 하고 누가 호출할 수 있는지와 함께 나열해 줘."
• "예약을 수정하거나 삭제하기 전에, 로그인한 사용자가 그 예약의 소유자인지 서버에서 확인해 줘."
• "이메일 API가 실패하더라도 예약은 저장하고 오류는 기록해 줘."
• "당분간은 제공업체의 테스트 모드를 써 줘."

Mythex의 API

Mythex는 여러분만의 API를 만들 수 있습니다. 웹 앱의 일부로 만들 수도 있고, 프런트엔드와 함께 실행되는 Node, Python(FastAPI), C#, Java로 된 별도의 백엔드로 만들 수도 있습니다. 또한 외부 서비스를 호출하는 코드도 작성합니다. 키는 채팅이 아니라 프로젝트 시크릿으로 추가하며, 미리보기에서도, 게시한 뒤에도 앱이 사용할 수 있습니다. 문서에는 모든 API 연동하기와 REST API 백엔드 만들기 레시피가 있습니다.

자주 묻는 질문