이 섹션에서는 Bubble의 공식 Plugin인 API Connector(커넥터)를 다룹니다. API 커넥터는 외부 애플리케이션으로 나가는 연결(Outgoing Request)을 만들고 이를 데이터 소스로 사용하거나 작업을 트리거하는 데 사용됩니다.
- 앞서 Bubble API 글에서 수신되는 API 요청(Incoming Request)을 다뤘습니다. 이러한 요청은 외부 시스템에서 시작되고 Bubble은 인증, 엔드포인트 및 매개변수를 기반으로 동작됩니다.
이것은 API 커넥터에 대한 심층 매뉴얼 문서입니다.
이 섹션에서는 API 커넥터를 사용해서 나가는 요청 (Outgoing Request : Bubble 앱이 외부 시스템에 요청을 보낼 때)의 동작에 대해 살펴보겠습니다.
- API 커넥터를 사용할 때 Bubble앱은 클라이언트이고 Bubble앱 외부의 API 서비스는 서버입니다.
- API 커넥터는 다른 애플리케이션에서 Bubble 앱으로 들어오는 호출을 처리합니다.
API 커넥터를 API 공급자가 제공하는 URL(Universal Resource Locator)로 지정하면 특정 리소스에 액세스 할 수 있습니다.
- 들어오는 요청(Incoming Request)과 마찬가지로 이러한 호출은 데이터를 받거나 수행할 작업을 요청할 수 있습니다.
- API 커넥터의 설정을 통해 구조적으로 어떻게 생겼는지 알 수 있습니다. 또한 GET, POST, PATCH 및 DELETE와 같은 메서드를 포함하는 HTTP 요청을 사용합니다.
API커넥터는 Bubble Plugin 스토어에서 설치(install)하여 사용합니다.
- Bubble의 플러그인 스토어는 Bubble과 커뮤니티에서 만든 수천 개의 플러그인을 제공합니다.
- 많은 플러그인을 사용하면 API 커넥터에서 설정할 필요 없이 잘 알려진 API 서비스에 빠르고 쉽게 연결할 수 있습니다.
(1) API 커넥터 설치
API 커넥터는 JSON 기반 RESTful 웹 API를 노출하는 모든 서비스에 연결할 수 있도록 Bubble의 개발 팀에서 구축한 특수 플러그인입니다. 이를 사용하여 API 호출을 추가하여 외부 서비스에서 데이터를 가져오거나 외부 서비스의 일부 작업을 트리거할 수 있습니다.
API 커넥터 설치
API 커넥터는 Bubble에서 만든 플러그인이며 사용하기 전에 앱에 설치해야 합니다.
앱에 플러그인을 설치하기:
- Bubble 메인 Panel의 좌측 Plugin(플러그인) 섹션으로 이동하고 플러그인 추가를 클릭
- 검색창에 API 커넥터 검색
- Install 버튼을 클릭
(2) 외부 API 문서 보기
모든 API 서비스는 각각 다르며 플랫폼에 성공적으로 연결할 수 있도록 대부분의 공급자는 API 설명서를 제공합니다. 해당 서비스를 인증하고 호출하는 방법을 이해하려면 외부문서를 사용하는 것이 중요하므로 시작하기 전에 이에 대해 알아보는 것이 좋습니다.
- Stripe과 같은 API공급자는 API 연결을 설정하는 방법에 대한 자세한 문서를 제공합니다.
- API를 처음 사용하는 경우 설명서가 처음에는 상당히 기술적인 것처럼 보일 수 있지만 RESTful API 스타일을 사용하면 대부분의 공급자가 유사한 표준을 따른다는 것을 알게 될 것입니다.
대부분의 API는 사용되기 전에 세 단계를 거칩니다.
- 먼저 API 서비스에 대한 *인증(authentication) 설정
- 두 번째로 사용하려는 다른 호출(Request Call)을 설정합니다.
- 호출을 *초기화(Initialize)하여 작동하는지 확인하고 서버의 응답을 확인합니다.
*인증(authentication) : 클라이언트가 누군지 확인하고 어떤 데이터를 요청할지 확인
*초기화(Initialize) : call 이 성공하는지 확인, response로 받아오는 데이터 확인
테스트 계정
- API 공급자는 당신이 실제 API 설정 변경(결제 등) 없이 API 호출을 테스트하는 데 사용할 수 있는 테스트 데모 계정을 제공합니다.
- 연결하려는 서비스가 위험 없이 모든 Call를 적절하게 테스트할 수 있는 테스트 환경을 제공하는지 확인하십시오.
(3) API Connector 설정
1. API 이름 지정 (보통 공급자 이름 지정)
새로운 API 요청 설정의 첫 번째 부분은 서비스에 이름을 지정하는 것입니다. 이것은 일반적으로 서비스를 구별하기 쉽게 Google, OpenWeatherAPI와 같은 설명이 포함된 이름(보통 공급자 이름)을 포함하여 자유롭게 지정합니다.
- API에 설명이 포함된 이름으로 만들면 다양한 공급자를 더 쉽게 구별할 수 있습니다.
- 이 이름은 나중에 추가할 다양한 호출들을 구성하기 위해 Bubble 편집기에서 사용됩니다. 따라서 관련 Call를 나중에 쉽게 찾을 수 있도록 이름을 사용하는 것이 좋습니다.
- API 이름은 Bubble앱의 클라이언트 측 코드의 일부가 되며 민감한 정보를 포함해서는 안 됩니다.
2. 인증 : Authentication
API 작동 방식에 대한 일반가이드에서 다룬 것처럼 많은 API 서비스에 인증이 필요합니다. 이는 클라이언트가 액세스해야 하는 리소스를 결정하기 위해 클라이언트가 *누구인지 식별하는 프로세스입니다.
1) 인증 방법
인증 방법에는 여러 가지가 있습니다.
- 대부분의 API 공급자는 인증 방법을 지정하는 문서를 온라인에서 찾아볼 수 있으며 고유한 API 토큰을 생성해야 하는 경우가 많습니다.
- 아래 목록은 가장 일반적인 인증 유형을 나타냅니다.
| 인증 방법 | 설명 |
| None or self-handled | 인증 불필요 |
| Private key in URL | 개인 키는 URL에 매개변수로 포함됩니다. |
| Private key in header | 개인 키는 요청에 HTTP 헤더로 포함됩니다. |
| HTTP Basic Auth | 클라이언트는 일반 텍스트로 사용자 이름과 암호를 보냅니다. |
| OAuth2 Password Flow | 클라이언트는 사용자 이름과 암호를 보내고 그 대가로 액세스 토큰을 돌려 받습니다. |
| OAuth2 User-Agent Flow | OAuth2 Password Flow과 유사하지만 사용자 에이전트용 |
| OAuth2 Custom Token | 클라이언트는 확인을 위해 custom 토큰을 서버로 보냅니다. |
| JSON Web Token (JWT) | 클라이언트는 확인을 위해 JSON 웹 토큰을 서버로 보냅니다. |
| Client-side SSL certificate | 클라이언트는 확인을 위해 서버에 SSL 인증서를 제공합니다 |
2) API 토큰/키 및 보안
API를 처음 사용하는 경우 여기에서 API 토큰을 비밀로 유지하는 것의 중요하다는 것을 알아야 합니다.
API 토큰은 원칙적으로 사용자 ID 및 암호와 같은 기능을 제공하고 API 공급자에게는 보안 및 유연성을 제공합니다.
- 접속을 쉽게 생성하고 해지할 수 있습니다. 일반적으로 실제 사람이 만들고 관리하는 사용자 이름과 비밀번호와 달리 API 토큰은 API 공급자가 쉽게 생성하고 해지할 수 있습니다. 이를 통해 API에 대한 접속을 쉽게 제어하고 보안 위반의 영향을 제한할 수 있습니다.
- 안전합니다. 일반적으로 API 토큰은 사용자 이름과 비밀번호 조합보다 더 안전합니다. 일반적으로 추측하거나 무차별로 대입하기 어렵기 때문입니다. 또한 보안을 더욱 향상하기 위해 정기적으로 교체할 수 있습니다.
- 편리합니다. 일반적으로 API 토큰은 특별한 처리가 필요하지 않기 때문에 개발자가 사용자 이름과 비밀번호 조합보다 작업하기 더 쉽습니다. 이렇게 하면 개발자가 API를 더 쉽게 사용할 수 있고 API 사용을 늘릴 수 있습니다.
- 사용자 ID, 암호와 마찬가지로 토큰은 관리하는 사람이 잘 유지 관리해야 합니다. Stripe과 같은 중요한 결제 서비스에 대한 토큰은 최대한 기밀로 처리해야 합니다.
- API 키/토큰은 애플리케이션의 클라이언트 측 소스 코드에 표시되기 때문에 옵션 세트나 온페이지 요소 및/또는 워크플로에 저장하면 안 됩니다.
87. Authentication (중급) : API 인증 bearer token, 인증 없이 접속, 사용자 인증, 관리자 인증 > 바로가기
3. 공유 헤더 설정: Shared Header
- 필요시 모든 Call에 공통으로 필요한 동일한 정보를 추가해야 합니다.
- 이는 인증과 관련된 개인 키(토큰)의 설정일 수 있지만 다른 일반적인 키 같은 Call의 예상 정보를 지정하는 콘텐츠유형 일 수 있습니다.
- 특정 헤더가 필요한지 확인하려면 API 제공자의 API 문서를 참조하세요.
4. 공유 파라미터 설정: Shared Parameter
- 위에서 설명한 헤더와 같이, 공유 매개변수는 관련 API의 모든 호출 공통으로 추가됩니다.
- 공유 매개변수는 헤더(Header)가 아닌 요청 Body(본문)에 추가됩니다.
- 헤더와 매개변수를 각 호출에 직접 추가하든 공유 헤더/매개변수 기능을 사용하든 기술적인 차이는 없습니다.
- 여기에 추가하면 시간이 절약되고 헤더와 매개변수를 더 쉽게 설정하고 관리할 수 있습니다.
5. API Call 추가
1) Call 추가 버튼
전 단계에서
- API 서비스에 이름을 지정하고
- 클라이언트로 인증(필요한 경우)했으므로
- 실제 호출을 추가할 차례입니다.
- call를 추가하려면 add another call(다른 통화 추가 ) 버튼을 클릭하세요.
- 다시 말하지만 다른 작업을 수행하기 전에 API Call이름을 지정해야 합니다.
- 이전에 설정한 API Call이름과 구별되고 관련 설명이 포함된 이름을 지정하십시오.
2) Use as Data 또는 Action : 드랍다운 선택
설정한 API 이름 옆에 Use as 옆 드랍다운 버튼으로 Data 또는 Action을 선택합니다.
드롭다운에서 이 call이 무엇에 사용될 것인지 Bubble에 알려야 합니다.
Data
- 데이터로 사용은 Bubble이 해당 API 호출을 데이터 소스로 취급함을 의미합니다.
- 당신의 앱에 데이터를 검색하도록 설정할 API Call에 이 설정을 하십시오.
- 사용 시에는 데이터 소스 드롭다운 목록의 Get datta from External API (외부 API에서 데이터 가져오기)에서 API data Call를 찾을 수 있습니다.
Action
- Action으로 사용하면 워크플로 편집기에서 API 호출을 Action으로 사용할 수 있습니다.
- 플러그인 아래의 워크플로 편집기에서 API Action Call을 찾을 수 있습니다.
3) HTTP 메서드 (GET, POST, PUT, PATCH, DELETE) 설정
특정 리소스에 대한 호출이 이루어지면 시작하려는 작업의 종류를 서버에 알려주는 HTTP 메서드를 지정해야 합니다.
가장 많이 사용되는 5가지 HTTP 메서드는 다음과 같습니다.
| 메서드 | 설명 |
| GET | 데이터 가져오기 |
| POST | 데이터 만들기 |
| PUT | 데이터 엡데이트 |
| PATCH | 데이터 대체 |
| DELETE | 데이터 삭제 |
- 때때로 HTTP method HTTP verv라고도 합니다.
- 일반적으로 위 표에 설명된 대로 사용되지만 액세스 하려는 리소스에 대한 올바른 HTTP 메서드를 찾으려면 API 공급자 설명서를 확인하세요.
4) The URL and endpoint
지난 시간에 API에 대한 글에서 RESTful API 호출이 URL을 사용하여 특정 자원을 식별하는 방법을 살펴보았습니다.
- 예를 들어, Bubble의 Data API (데이터베이스에 대한 외부 시스템 액세스 권한을 부여하는 데 사용됨) 및 Workflow API (외부 시스템에 워크플로에 대한 액세스 권한을 부여하는 데 사용됨)를 살펴볼 때 Bubble이 선택한 각 데이터 유형에 대해 고유한 URL을 생성하는 방법을 살펴보았습니다.
: 외부 RESTful API는 동일한 방식으로 작동합니다.
- 원하는 리소스에 도달하기 위해 Bubble 애플리케이션을 특정 URL로 지정합니다. HTTP 메서드와 endpoint는 함께 요청되는 특정 작업을 정의하는 고유한 API endpoint를 형성합니다.
- 예를 들어 "/users" 끝점에 대한 GET 요청은 API에서 사용자 목록을 검색하는 데 사용될 수 있고 "/users" 끝점에 대한 POST 요청은 새 사용자를 만드는 데 사용될 수 있습니다.
올바른 endpoint 찾기
- endpoint는 HTTP 메서드와 URL의 조합입니다.
- 사용 방법과 URL은 API 서비스마다 다르며 일반적으로 API 공급자의 설명서를 참조하여 올바른 endpoint를 찾을 수 있습니다.
*API 커넥터 설정과 더불어 보안에 대해서 알아보려면 다음의 문서를 읽어보세요
API Connector 플러그인 보안 (중급) : API Key 보안, Parameter 보안, API Call 보안, URL 보안 > 바로가기
