Bubble.io API Provider 활용법｜내 버블 앱을 외부 REST API로 개방하는 방법

2026년 9월 28일 읽는 시간 약 18분

Bubble.io로 만든 앱의 데이터를 외부 웹사이트나 모바일 앱, 사내 시스템에서 사용하려면 어떤 기능을 켜야 할까요? 많은 사용자가 API Connector의 API Provider라는 표현부터 찾지만, 외부 요청을 받는 실제 기능은 Bubble의 Data API와 Workflow API입니다. 즉, Bubble 앱이 외부 서비스를 호출할 때는 API Connector를 사용하고, 반대로 외부 시스템이 내 Bubble 앱을 호출하게 만들 때는 Bubble API를 개방해야 합니다.

이 글에서는 Bubble 앱을 REST API 제공 서버처럼 구성하는 과정을 다룹니다. 단순히 설정을 켜는 방법에 그치지 않고 데이터 조회와 업무 처리용 엔드포인트의 차이, 인증 방식, Privacy Rules, JSON 응답 설계, Postman과 cURL 테스트, 운영 환경 배포 전 점검 항목까지 순서대로 정리합니다.

이 글에서 말하는 ‘API Provider’는 내 Bubble 앱이 외부 요청을 받는 API 제공자 역할을 뜻합니다. Bubble 편집기에서 외부 REST API를 개방하는 핵심 메뉴는 Settings의 API 설정과 Backend workflows입니다.

1. Bubble API의 방향부터 구분해야 하는 이유

API 연동에서 가장 자주 발생하는 실수는 요청 방향을 반대로 이해하는 것입니다.

목적	Bubble에서 사용하는 기능	Bubble 앱의 역할
외부 지도·결제·AI API 호출	API Connector	클라이언트
외부 시스템에 DB 데이터 제공	Data API	서버·API 제공자
외부 요청으로 로직 실행	Workflow API	서버·API 제공자
다른 Bubble 앱과 연결	Bubble App Connector	연결 구조에 따라 다름

예를 들어 외부 쇼핑몰이 Bubble에 주문 정보를 전달하게 하려면 Workflow API가 적합합니다. 반면 사내 대시보드가 Bubble의 상품 데이터를 조회해야 한다면 Data API를 사용할 수 있습니다. 데이터베이스를 직접 공개하지 않고 필요한 결과만 가공해 반환하고 싶다면 Workflow API가 더 안전하고 유연합니다.

2. Data API와 Workflow API 중 무엇을 선택할까?

Data API가 적합한 경우

Data API는 Bubble 데이터베이스의 특정 Data type을 REST 방식으로 조회하거나 생성·수정·삭제할 때 사용합니다. 외부 관리 도구에서 상품 목록을 읽거나 별도의 앱에서 고객 문의 데이터를 등록하는 구조에 알맞습니다.

다만 Data type을 그대로 노출하므로 공개 필드와 Privacy Rules를 세밀하게 설계해야 합니다. User, 결제 정보, 내부 메모처럼 민감한 필드가 포함된 데이터라면 편의성만 보고 Data API를 여는 것은 피하는 편이 좋습니다.

Workflow API가 적합한 경우

Workflow API는 외부 요청을 받아 Backend workflow를 실행합니다. 입력값 검증, 데이터 조회, 계산, 저장, 이메일 발송 등 여러 단계를 하나의 엔드포인트로 묶을 수 있습니다. Return data from API 액션을 사용하면 필요한 값만 JSON으로 반환할 수도 있습니다.

다음과 같은 상황에서는 Workflow API가 더 적합합니다.

외부에서 전달된 주문번호의 유효성을 확인해야 할 때
여러 Data type의 값을 조합해 하나의 JSON으로 반환할 때
내부 데이터 구조를 외부에 직접 공개하고 싶지 않을 때
요청자의 권한에 따라 처리 결과를 다르게 해야 할 때
웹훅을 받아 후속 작업을 자동으로 실행할 때

실무에서는 공개 범위를 최소화하기 위해 Data API보다 Workflow API로 필요한 기능만 만드는 경우가 많습니다.

3. Bubble 앱에서 Workflow API 활성화하기

먼저 Bubble 편집기에서 Settings → API로 이동합니다. Enable Workflow API and backend workflows 항목을 활성화하면 Backend workflows 탭과 Workflow API 주소를 사용할 수 있습니다.

그다음 Backend workflows에서 새로운 API workflow를 만듭니다. 예시로 상품 재고를 확인하는 get_product_stock 엔드포인트를 구성해 보겠습니다.

Backend workflows에서 새 API workflow를 생성합니다.
이름을 get_product_stock으로 지정합니다.
외부 호출을 허용하는 Expose as a public API workflow를 활성화합니다.
요청 방식은 조회 목적이면 GET, 데이터를 전달하거나 처리하면 POST를 선택합니다.
product_code라는 text 타입 파라미터를 추가합니다.
해당 코드로 Product를 검색하고 결과를 검증합니다.
마지막 단계에 Return data from API를 추가합니다.

워크플로 이름은 URL의 일부가 되므로 공백과 특수문자를 피하고 기능을 알아볼 수 있게 작성하는 것이 좋습니다. 이미 외부 서비스와 연결한 뒤 이름을 바꾸면 호출 주소도 달라질 수 있으므로 운영 중인 엔드포인트는 신중하게 변경해야 합니다.

4. 엔드포인트 주소 구성 이해하기

Bubble Workflow API의 기본 구조는 다음과 같습니다.

https://앱도메인/api/1.1/wf/워크플로이름

개발 버전은 일반적으로 주소에 version-test가 포함됩니다.

https://앱이름.bubbleapps.io/version-test/api/1.1/wf/get_product_stock

Live 배포 후에는 다음과 같은 운영 주소를 사용합니다.

https://앱이름.bubbleapps.io/api/1.1/wf/get_product_stock

커스텀 도메인을 연결했다면 Bubble 기본 도메인 대신 해당 도메인을 사용할 수 있습니다. 개발용과 운영용 URL을 혼용하면 테스트 DB에는 데이터가 있는데 Live DB에서는 검색되지 않는 것처럼 보일 수 있습니다. 외부 서비스에 등록한 주소가 어느 환경을 가리키는지 반드시 확인해야 합니다.

5. 파라미터는 수동 정의가 관리하기 쉽다

API workflow의 파라미터는 수동으로 추가하거나 POST 요청 샘플을 감지해 자동으로 정의할 수 있습니다. 일반적인 REST API라면 이름과 타입을 직접 정하는 방식이 유지보수에 유리합니다.

예를 들어 재고 조회 API에는 다음과 같은 입력값을 둘 수 있습니다.

파라미터	타입	필수 여부	용도
product_code	text	필수	조회할 상품 코드
include_reserved	yes/no	선택	예약 재고 포함 여부
request_id	text	선택	중복 요청 추적용 값

GET 요청의 값은 query string으로 전달합니다.

GET /api/1.1/wf/get_product_stock?product_code=P1001

POST 요청은 일반적으로 JSON body를 사용합니다.

{
  "product_code": "P1001",
  "include_reserved": false,
  "request_id": "req-20260922-001"
}

날짜, 숫자, yes/no 등 타입을 정확히 지정해야 Bubble 내부에서 불필요한 텍스트 변환을 줄일 수 있습니다. 선택값은 Optional로 설정하고, 누락되었을 때 적용할 기본 로직도 함께 설계합니다.

6. 예측 가능한 JSON 응답 만들기

외부 시스템이 안정적으로 연동하려면 성공과 실패 응답의 모양이 일정해야 합니다. Return data from API 액션에서 다음처럼 공통 구조를 정할 수 있습니다.

{
  "success": true,
  "code": "OK",
  "message": "재고 조회가 완료되었습니다.",
  "data": {
    "product_code": "P1001",
    "available_stock": 27
  }
}

상품이 없을 때도 전혀 다른 형식 대신 같은 키를 유지합니다.

{
  "success": false,
  "code": "PRODUCT_NOT_FOUND",
  "message": "일치하는 상품을 찾을 수 없습니다.",
  "data": null
}

success, code, message, data처럼 일관된 규칙을 정하면 외부 개발자가 응답을 처리하기 쉽습니다. 내부 Thing 전체를 반환하기보다 상대 시스템에 필요한 값만 골라 보내는 것이 정보 노출과 데이터 결합도를 줄이는 데 도움이 됩니다.

7. 인증 없이 공개하면 안 되는 이유

외부에서 호출할 수 있다는 것과 누구나 호출해도 된다는 것은 다릅니다. Bubble의 API workflow에는 접근 수준을 결정하는 인증 설정이 있으며, 구성에 따라 인증 없음, 로그인한 사용자, 관리자 토큰 등의 범위를 선택할 수 있습니다.

인증이 없는 엔드포인트는 URL을 아는 누구나 반복 실행할 수 있습니다. 데이터 생성, 이메일 발송, 결제 처리처럼 비용이나 상태 변경이 발생하는 워크플로라면 무단 호출과 과도한 Workload Unit 사용으로 이어질 수 있습니다.

서버 간 연동에서는 보통 HTTP 헤더에 Bearer 토큰을 전달합니다.

Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

관리자 API 토큰은 강력한 권한을 가지므로 브라우저 JavaScript, 페이지의 숨은 입력값, 공개 GitHub 저장소에 넣어서는 안 됩니다. 외부 서버의 환경변수나 비밀 관리 기능에 저장하고, 용도별로 구분해 발급하며, 유출이 의심되면 즉시 폐기하고 교체해야 합니다.

웹훅처럼 상대 서비스가 Bubble 방식의 로그인이나 토큰을 지원하지 않는다면 별도의 서명값이나 secret을 헤더로 전달받아 검증하는 구조를 고려할 수 있습니다. 이때 단순히 secret 일치 여부만 확인하지 말고 요청 시간, 고유 이벤트 ID, 중복 처리 여부까지 검사하면 재전송 공격과 이중 저장 위험을 줄일 수 있습니다.

8. Privacy Rules와 ‘Ignore privacy rules’ 주의점

Workflow API에서 Privacy Rules는 워크플로 실행 자체를 막는 장치라기보다, 실행 과정에서 어떤 데이터를 검색하고 볼 수 있는지를 제한합니다. 따라서 인증된 사용자 토큰으로 요청했는데 검색 결과가 비어 있다면 데이터가 없는 것이 아니라 Privacy Rules 때문에 보이지 않는 상황일 수 있습니다.

Ignore privacy rules when running the workflow 옵션을 사용하면 문제를 빠르게 우회할 수 있지만, 외부 요청이 관리자 수준으로 데이터를 다루게 될 수 있습니다. 다음 조건을 모두 검토한 뒤 제한적으로 사용해야 합니다.

요청자가 충분히 인증되었는가?
검색 대상이 요청자 소유 데이터로 제한되는가?
반환 필드에 이메일·전화번호·결제 정보가 포함되지 않는가?
파라미터 조작으로 다른 사용자의 레코드를 지정할 수 없는가?
해당 옵션이 반드시 필요한 이유를 설명할 수 있는가?

가장 안전한 원칙은 필요한 데이터만 검색하고, 필요한 값만 반환하며, 우회 권한은 최소화하는 것입니다.

9. Data API를 개방하는 방법

외부 시스템이 데이터베이스 레코드를 직접 다뤄야 한다면 Settings → API → Enable Data API를 켠 뒤 공개할 Data type만 선택합니다. 모든 타입을 일괄 노출하지 말고 실제 연동에 필요한 타입만 허용합니다.

데이터 조회 주소는 일반적으로 다음 구조를 사용합니다.

https://앱도메인/api/1.1/obj/데이터타입

특정 레코드는 고유 ID를 덧붙여 접근합니다.

https://앱도메인/api/1.1/obj/product/레코드고유ID

Data API를 활성화했다고 해서 모든 데이터가 자동으로 안전하게 정리되는 것은 아닙니다. Privacy Rules에서 검색 가능 여부와 필드별 공개 범위를 점검하고, API를 통한 생성·수정·삭제 권한도 필요한 수준으로 제한해야 합니다. 민감한 필드가 섞여 있다면 API 전용 Data type을 따로 만들거나 Workflow API를 통해 가공된 결과만 제공하는 편이 낫습니다.

10. cURL로 REST API 테스트하기

브라우저 주소창만으로는 POST body와 인증 헤더를 제대로 확인하기 어렵습니다. Postman이나 cURL을 이용하면 실제 외부 시스템과 유사한 방식으로 테스트할 수 있습니다.

curl -X POST 'https://앱이름.bubbleapps.io/version-test/api/1.1/wf/get_product_stock' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "product_code": "P1001",
    "include_reserved": false,
    "request_id": "req-20260922-001"
  }'

테스트할 때는 다음 순서로 확인하면 원인을 찾기 쉽습니다.

인증 헤더 없이 호출해 접근이 차단되는지 확인합니다.
잘못된 토큰으로 다시 호출해 동일하게 거부되는지 봅니다.
필수 파라미터를 누락해 오류 응답 구조를 확인합니다.
정상 값으로 호출해 데이터와 타입이 예상대로 반환되는지 검사합니다.
같은 request_id를 두 번 보내 중복 처리가 방지되는지 확인합니다.
Development와 Live 환경에서 각각 테스트합니다.

11. 자주 발생하는 오류와 해결 방법

엔드포인트를 찾을 수 없는 경우

Workflow API가 비활성화되어 있거나 해당 workflow의 외부 공개 설정이 꺼져 있을 수 있습니다. 워크플로 이름과 URL 철자, version-test 포함 여부도 확인합니다.

인증 오류가 발생하는 경우

Authorization: Bearer 토큰 형식에 공백이나 오탈자가 없는지 확인합니다. Development와 Live 배포 상태가 다르면 새 설정이나 토큰 변경이 운영 버전에 적용되지 않았을 수도 있습니다.

요청은 성공했는데 데이터가 비어 있는 경우

Privacy Rules 때문에 검색 결과가 제한되었거나 테스트 DB와 Live DB를 혼동했을 가능성이 큽니다. 요청 주체의 권한, 검색 조건, 데이터가 저장된 환경을 차례대로 확인합니다.

POST 값이 Bubble에서 인식되지 않는 경우

Content-Type: application/json 헤더와 JSON 문법을 점검합니다. Bubble에 정의한 파라미터명과 body의 key가 정확히 일치하는지도 확인해야 합니다.

조건이 맞지 않아 외부 서비스가 재요청하는 경우

워크플로의 Only when 조건이 충족되지 않으면 오류 상태가 반환될 수 있습니다. 웹훅 제공 업체가 성공 상태를 받지 못해 같은 이벤트를 반복 전송할 수 있으므로, 성공 처리 기준과 재시도 정책을 함께 확인합니다. 무조건 성공으로 응답하게 바꾸기보다는 이벤트 ID를 기록해 중복 처리를 차단하는 것이 먼저입니다.

12. 운영 환경에 배포하기 전 보안 점검표

외부에 필요한 API workflow만 공개했는가?
인증 없이 실행 가능한 엔드포인트가 남아 있지 않은가?
관리자 토큰을 클라이언트 화면이나 소스 코드에 넣지 않았는가?
Privacy Rules가 사용자별 데이터 접근을 제한하는가?
입력값의 길이, 형식, 허용 범위를 검사하는가?
이메일·전화번호·내부 ID 등 불필요한 값이 응답에 포함되지 않는가?
동일 이벤트가 재전송되어도 한 번만 처리되는가?
실패 기록을 Logs에서 추적할 수 있는가?
비정상적인 반복 호출을 제한할 구조가 있는가?
Development 테스트 후 Live에 배포하고 운영 URL을 다시 확인했는가?

13. 유지보수하기 쉬운 API 설계 원칙

첫째, 엔드포인트 하나에 너무 많은 기능을 넣지 않습니다. 조회, 생성, 상태 변경을 구분하면 권한과 오류를 관리하기 쉽습니다.

둘째, 외부 시스템이 Bubble의 내부 필드 구조에 직접 의존하지 않게 합니다. 내부 필드명을 변경할 가능성이 있다면 Workflow API에서 응답 키를 고정해 반환하는 방식이 유리합니다.

셋째, 기존 응답 키의 의미를 갑자기 바꾸지 않습니다. 큰 변경이 필요하면 /v2/처럼 버전을 나누거나 새 workflow를 만든 뒤 충분한 전환 기간을 둡니다.

넷째, request_id, 요청 시각, 처리 결과, 오류 코드 등을 로그용 Data type에 남깁니다. 단, 비밀번호와 전체 토큰 같은 비밀값은 로그에 저장하지 않습니다.

다섯째, 검색 조건을 구체적으로 작성합니다. 제한 없는 Do a search for 뒤에 클라이언트 측 필터를 적용하는 방식은 불필요한 데이터 조회와 Workload 증가로 이어질 수 있습니다.

마무리

Bubble.io 앱을 외부 REST API로 개방할 때 가장 먼저 결정해야 할 것은 ‘데이터를 직접 공개할 것인지’와 ‘정해진 로직만 실행하게 할 것인지’입니다. 전자는 Data API, 후자는 Workflow API가 담당합니다. 특히 민감한 데이터나 복잡한 업무 규칙이 포함된 서비스라면 Workflow API로 필요한 기능만 노출하고 인증, Privacy Rules, 입력 검증, 일정한 JSON 응답을 함께 설계하는 편이 안전합니다.

API가 정상 응답한다고 해서 연동이 완성된 것은 아닙니다. 잘못된 토큰, 누락된 값, 중복 요청, 권한이 없는 사용자 같은 실패 상황까지 테스트해야 실제 운영에서도 안정적으로 사용할 수 있습니다. 처음에는 작은 조회 엔드포인트 하나로 시작한 뒤 로그와 사용량을 확인하면서 범위를 넓히는 것이 Bubble API를 관리하는 현실적인 방법입니다.