106. DATA API Request (중급) : postman API 테스트, GET, POST, PATCH, BULK POST, Pagination, Sorting

이 섹션에서는 데이터 API를 사용하여 수행할 수 있는 다양한 Request를 다룹니다.

• Bubble의 데이터 API는 당신의 앱 데이터베이스를 읽고, 생성하고, 편집하고, 삭제할 수 있는 액세스 권한을 외부의 다른 애플리케이션에게 제공합니다.

(1) Intro - 예제 설정

아래의 다양한 설명으로 이동하기 전에 이 글 전체에서 언급할 예제를 소개하겠습니다.

• 부동산 소유자가 임대 주택(단위는 unit)을 관리할 수 있는 플랫폼을 구축한다고 상상해 보세요

 

: 예제를 심플하게 다루기 위해 Rental Unit이라는 데이터 type에 몇 가지 필드를 추가합니다.

Field name	Field type
unit name	text
unit number	number
unit address	geography address

• 원하는 시스템에서 호출을 설정할 수 있지만 이 예제에서는 *Postman이라는 도구를 사용하여 Bubble 앱에 Request를 시도합니다.

 

*Postman이란?

Postman은 API를 테스트하고 문서화할 수 있는 온라인 서비스(도구)입니다. HTTP Request를 보내고 Response를 보기 위한 사용자 친화적인 인터페이스를 제공하며 요청 저장 및 구성, 자동화된 테스트, 다양한 인증 방법 지원과 같은 기능을 포함합니다.

• Bubble 애플리케이션에서 들어오고 나가는 API 요청을 모두 테스트하는 데 이를 사용하는 것이 도움이 됩니다.

 

(2) 데이터 생성

여기서도 위의 예제를 이어서 설명하겠습니다. 부동산 임대관리를 하려면 관리할 부동산이 있어야 하겠죠. 여기에서 가장 먼저 해야 할 일은 데이터 API를 이용해여 새로운 임대 주택(unit)을 만드는 것입니다.

 

1. [새로운 임대 주택(unit) 만들기] 프로세스

: 프로세스는 다음과 같습니다.

1. POST 요청이 Postman에서 RentalUnit(데이터 type 이름) 엔드포인트로 전송됩니다.
2. Bubble 앱이 요청(request)을 수신하고 처리합니다. 새로운 임대 주택(unit)이 생성되었습니다.
3. Bubble 앱은 요청(request)이 성공했음을 알리기 위해 Postman에 응답(response)을 다시 보냅니다.

 

2. 데이터 API 구성 요약

: 잠시 API가 어떻게 구성되어 있는지 빠르게 살펴보겠습니다.

1. Endpoint: URL은 우리 가 액세스하려는 리소스를 가리킵니다.
2. HTTP method: 우리가 사용하는 HTTP 메서드는 무언가 를 생성하기를 원하기 때문에 POST입니다.
3. Header: 헤더에는 우리를 인증하는 데 사용되는 전달자 토큰(bearer token)과 본문 형식(JSON)이 포함되어 있습니다.
4. Body: 본문에는 임대 주택에 저장하려는 매개변수 (unit의 이름, 번호 및 주소)가 포함되어 있습니다.

 

3. Request 테스트 보내기

1) 사용자 정의 브랜치에서 개발하는 경우 URL에 브랜치의 ID가 포함된다는 점에 유의하세요.

• Main 브랜치의 경우 항상 version-test입니다.

2) Postman에서 새 Request(요청)를 생성하고 이름을 'Create Rental Unit'으로 지정합니다.

• 이름은 단지 다양한 요청을 식별, 정리하기 위한 것입니다. (기능에는 아무 영향 없음)

3) URL 표시줄에 type 이름과 결합된 루트 URL을 입력합니다.

• https://myapp.bubbleapps.io/version-test/api/1.1/obj/rentalunit

4) 다음으로 새 임대 주택(unit)을 생성할 때 포함할 매개변수를 추가해야 합니다.

key	value
unit name	unit A
unit number	3
unit address	33 Nassau Avenue, Brooklyn, NY 11222

• 마지막 필드인 단위 주소는 유효한 Google 지도 주소여야 합니다.(구글에서 검색 시 나옴)

 

Postman에서 구현한 테스트 호출은 다음과 같아야 합니다.

postman POST예제

 

• 이 스크린숏에서 HTTP 메서드(POST), 엔드포인트 및 전송하려는 매개변수를 볼 수 있습니다.
• 이제 SEND 버튼을 클릭하여 Postman에서 request를 테스트할 준비가 되었습니다.

 

4. API 구조

앱 서버로 전송되는 API 구조는 다음과 같습니다.

1) Header

Authorization: Bearer <token>
User-Agent: PostmanRuntime/7.30.0
Accept: /
Cache-Control: no-cache
Postman-Token: <token>
Host: myapp.bubbleapps.io
Accept-Encoding: gzip, deflate, br
Connection: keep-alive

2) Body

Unit name: "Unit A"
Unit number: "3"
Unit address: "33 Nassau Avenue, Brooklyn, NY 11222"j

3) Response

Request가 버블 서버에 의해 처리되면 성공 또는 오류 코드와 함께 Request에 연결된 관련 정보와 함께 Response(응답)을 클라이언트에 다시 보냅니다.

 

이 Request(요청)의 경우 두 가지 데이터가 클라이언트로 다시 전송됩니다.

• 요청 상태: 여기서는 '성공'(success)
• 우리가 생성한 임대 주택(unit)의 'unique ID'

이 역시 JSON 형식으로 전송되며 다음과 같습니다.

{
"status": "success",
"id": "1672236233855x229135430406542270"
}

 

(3) 데이터변경하기

이제, 방금 생성한 임대 주택(unit)에 몇 가지 사항을 변경해 보겠습니다.

• 짐작하셨겠지만, 데이터 생성과 변경의 호출(Call) 사이에는 중요한 차이점이 있습니다.
• 먼저, 특정 항목을 변경하려면 Request(요청)에서 해당 항목을 식별해야야 만 합니다.
• 운 좋게도, 위의 Request(요청)의 마지막에 Response(응답)을 보면 unique ID가 있으므로 이를 사용하여 올바른 임대 주택(unit)을 찾고 변경할 수 있습니다.
• unique ID 필드로 데이터베이스를 검색하는 경우를 lookup이라고 합니다.

 

1. 데이터 변경(PATCH) 프로세스

: 이번에는 어떤 과정을 거치게 될지 살펴보겠습니다.

1. unique ID를 포함하여 Postman에서 RentalUnit 엔드포인트로 PATCH 요청이 전송됩니다.
2. Bubble 앱이 요청을 받습니다.
3. 서버는 unique ID에 대한 조회를 수행합니다.
4. 임대 unit가 변경되었습니다.
5. Bubble 앱은 Request(요청)이 성공했음을 알리기 위해 Postman에 Response를 다시 보냅니다.

 

2. 데이터 변경(PATCH) Request(요청)

Postman에서 HTTP 메서드를 POST에서 PATCH로 변경한 다음, 유형 이름 뒤에 앞서 생성한 임대 주택 (unit)의 unique ID를 추가합니다. 전체 URL은 다음과 같습니다.

https://myapp.bubbleapps.io/version-test/api/1.1/obj/rentalunit/

 

• 이제 매개변수 섹션으로 이동하여 몇 가지 추가 변경을 수행합니다.
• 지금은 이름만 변경하려고 하므로 unit number 및 unit address 필드를 제거할 수 있습니다.
• 그러면 매개변수가 하나만 남게 됩니다.

KEY	VALUE
unit name	new name

Postman에서 request(요청) 설정은 다음과 같습니다.

 

PATCH 예시

•  사진과 같이 HTTP 메서드를 PATCH로 변경했습니다.
• 이제 SEND 버튼을 클릭하여 시도해 보겠습니다.

 

3. 데이터 변경(PATCH) Response

이러한 종류의 작업에 대해서는 성공 여부를 아는 것 외에는 어떤 응답도 필요하지 않습니다.

• 결국 우리는 어떤 레코드를 변경하고 있는지 이미 알고 있으므로 서버가 unique ID를 보낼 필요가 없습니다.
• 이 경우 Bubble 앱은 상태 코드 201과 빈 본문으로 Response(응답)합니다.

 

(4) 대량(Bulk) 생성

지금까지 설정한 Request(요청)은 단일 레코드에 대해 작동했습니다. 즉, 우리는 한 가지 새로운 레코드를 만들고 한 가지 필드를 변경했습니다.

• 이 시나리오에서는 Data API의 대량 기능을 사용하여 하나의 Request(요청)으로 여러 항목을 생성해 보겠습니다. 이는 데이터베이스에 있는 항목의 목록을 빠르게 생성할 수 있는 매우 강력한 기능입니다.

 

1. 주의사항

• 대량 생성 기능은 목록을 생성하는 가장 빠른 방법이지만, 데이터베이스 레코드를 대량 생성할 경우 서버 용량을 많이 소모할 수 있으므로 앱 용량에 유의해야 합니다.
• 대량 생성 기능을 사용할 때 레코드 수는 1,000개로 엄격하게 제한됩니다.
• 또한 요청을 처리하는 데 4분 이상 소요되면 시간 초과되어 취소됩니다.

 

2. 대량생성 Request

 

1) endpoint 설정

• 우리는 무언가를 생성하고 있기 때문에 여전히 POST HTTP 메소드를 사용할 것입니다.
• 여러 레코드를 생성하고 싶다고 Bubble 앱에 알리려면 엔드포인트를 변경해야 합니다.
• 엔드포인트에 대량(bulk)이라는 단어를 추가하여 다음과 같이 만듭니다.

POST https://myapp.bubbleapps.io/api/1.1/obj/rentalunit/bulk

 

2) parameter 설정

다음으로 변경해야 할 사항은 매개변수(parameter)의 형식을 JSON이 아닌 Text로 지정한다는 점을 Bubble에 알리는 것입니다.

• 이를 변경하려면 Body 섹션으로 이동하여 형식으로 Raw를 선택하세요
• 그런 다음 오른쪽 끝까지 드롭다운을 확인하고 Text로 설정하세요
• 확인: 이제 Header로 이동하면 콘텐츠 유형이 plain/text로 변경된 것을 볼 수 있습니다.

 

또한 매개변수(parameter)의 보내는 형식도 변경해야 합니다.

• 이번에는 전체 데이터 타입 이름을 사용합니다. (rentunit 대신 Rental unit)
• 생성하려는 각 레코드마다 한 줄씩을 사용합니다.
• 생성에 필요한 모든 매개변수를 포함해야 합니다. 누락된 필드는 생성된 레코드에서 비어 있게 됩니다.(또는 해당 필드가 있는 경우에는 기본값으로 채워짐)

Body섹션에서 다음의 형식(구조)으로 필드를 작성합니다.

{“Field1”: Value, “Field2”: “Value”} 
{“Field1”: Value, “Field2”: “Value”}

즉, 우리가 보내는 Rental unit의 경우 다음과 같아야 합니다.

{"Unit name": "New apartment", "Unit number": 5}
{"Unit name": "Old apartment", "Unit number": 6}

문자열은 따옴표로 묶어야 하며 숫자(정수)는 그렇지 않습니다.

BULK POST 예시

엔드포인트에 BULK을 추가하고 본문 유형을 RAW - TEXT로 변경했습니다.

 

3. 대량생성 Response

대량 기능을 사용하면 Bubble은 당신이 생성하려고 시도한 각 항목에 대해 한 줄의 응답을 제공합니다. 위의 예제의 응답은 다음과 같습니다.

{"status":"success","id":"1672396136196x664154886510492300"}
{"status":"success","id":"1672396136197x330332849009372400"}

• 기억하시겠지만 이는 여러 줄의 생성으로 단일 레코드를 생성할 때 얻은 것과 동일한 Response(응답)입니다. 라인 중 하나를 엉망으로 만들었다면 해당 특정 라인에 대해 오류 메시지가 표시됩니다.

{"status":"error","message":"Could not parse as JSON: {\"Unit name\": \"New apartment, \"Unit number\": 5}"}{"status":"success","id":"1672396782256x592646320029190300"}

이 예시에서는 New apartment 뒤에 따옴표를 입력하지 않아서, Bubble이 구문 분석할 수 없습니다. 보시다시피 올바른 형식의 두번째 줄의 레코드 제대로 생성되었습니다.

 

(5) 데이터 검색(GET)

이 예제에서는 위의 마지막 작업과 거의 동일한 작업을 수행하지만 약간 다릅니다.

• 조회(unique ID로 레코드를 직접 식별)를 수행하는 대신 검색을 수행합니다. (검색:기준과 일치하는 기록을 하나 이상 찾기)
• 이를 설정할 때 검색 대상이 어떻게 구성되어 있는지 생각하는 것이 도움이 됩니다.
• 검색할 데이터 type이 무엇인지 알려야 하며, 검색 범위를 좁히기 위해 제약 조건을 추가해야 합니다.

 

1. 데이터 검색 Request

 

1) endpoint 설정

• 먼저 HTTP 메서드에 대해 생각해 봅시다.
• 데이터를 변경하기보다는 데이터를 찾고 싶기 때문에 GET 메서드를 사용할 것입니다.
• 여전히 RentalUnits를 검색하는 중이므로 unique ID를 제거한다는 점을 제외하고 마지막 요청과 동일한 엔드포인트를 사용합니다.

 

2) 제약조건 설정

이제 제약 조건을 설정해 보겠습니다.

• 데이터베이스에는 순차적으로 번호가 매겨진 6개의 임대 주택(unit)이 있습니다.
• unit number 필드를 사용하여 숫자가 3보다 크고 이름에 "Unit"이 포함된 주택(unit)을 검색하겠습니다.

 

Data API reference에서 모든 제약 조건 유형 목록을 찾을 수 있습니다.

• params 섹션에서는 constraint(제약 조건)이라는 매개 변수 하나를 추가합니다.
• 그런 다음다음 형식으로 제약 조건을 추가합니다.

[ { "key": "unitname", "constraint_type": "text contains", "value": "Unit” } ,{ "key": "unitnumber", "constraint_type": "greater than", "value": "3" }]

해당 조각의 논리를 분석해 보겠습니다.

두 가지 제약 조건이 있으며 각 제약 조건은 중괄호로 묶여 있습니다.

각 제약조건에는 세 가지 데이터가 포함됩니다.

1. Key : 제약 조건을 적용하려는 필드의 이름(unitname), 넘버(unitnumber)
2. Constraint_type : 적용하려는 제약 조건 유형, 텍스트(text constains), ~ 보다 큰 수(greater than)
3. Value : 찾고자 하는 값 (Unit), (3)

• 각 데이터 포인트는 쉼표로 구분되고 따옴표로 묶여 있습니다.
• 각 제약 조건은 쉼표로 구분되며 전체 매개변수는 대괄호로 묶입니다.

이제 SEND를 눌러 실행해 보겠습니다.

 

2. 데이터 검색 Response

Bubble이 반환하는 내용은 다음과 같습니다.

 

{
"response": {
"cursor": 0,
"results": [
{
"Modified Date": "2022-12-30T11:03:11.097Z",
"Created Date": "2022-12-30T11:03:11.097Z",
"Created By": "admin_user_securitybook_test",
"Unit name": "Rental unit 4",
"Unit number": 4,
"_id": "1672398191097x872601726695236800"
},
{
"Modified Date": "2022-12-30T11:03:11.098Z",
"Created Date": "2022-12-30T11:03:11.098Z",
"Created By": "admin_user_securitybook_test",
"Unit name": "Rental unit 5",
"Unit number": 5,
"_id": "1672398191098x642899010515676700"
},
{
"Modified Date": "2022-12-30T11:03:11.099Z",
"Created Date": "2022-12-30T11:03:11.098Z",
"Created By": "admin_user_securitybook_test",
"Unit name": "Rental unit 6",
"Unit number": 6,
"_id": "1672398191098x774874860707789600"
}
],
"count": 3,
"remaining": 0
}
}

보시다시피 JSON은 읽기 쉬운 형식입니다.

• 우리는 Bubble 데이터베이스에서 데이터와 해당 필드를 명확하게 인식할 수 있습니다.
• count 값은 이 응답의 결과 수를 표시하고 remaining 값은 남은 레코드 수를 표시합니다.
• Bubble은 기본적으로 100개의 레코드를 반환하지만 페이지 쪽수 매김 기능(Pagination)을 사용하여 반환하려는 숫자를 설정할 수도 있습니다.(아래 설명)

 

3. Pagination (쪽수 매기기)

Pagination(쪽수매김)은 검색 결과를 더 작고 관리하기 쉬운 데이터 덩어리인 '페이지'로 나누는 것을 의미합니다.

• 데이터 API는 기본적으로 결과를 100개 레코드의 페이지로 분할하지만 몇 가지 추가 매개변수를 제공하여 원하는 방식으로 작동하도록 Pagination(쪽수 매김)을 설정할 수 있습니다.

 

1) Pagination에서 필요한 변수

: Pagination(쪽수 매김)을 설정하려면 두 개의 매개변수가 더 필요합니다.

1. Cursor: 목록 시작 위치(Bubble 편집기의 items from# 과 유사)
2. Limit: 결과로 받고 싶은 데이터 수(Bubble 편집기의 items to# 과 유사)

 

2) parameter 추가

:위의 예시에서 제약 조건 매개변수를 추가한 것처럼 이를 추가합니다.

• Postman에서 Params 섹션으로 이동하여 두 개의 새 매개변수 행인 Cursor와 Limit을 추가합니다.
• 두 번째 레코드부터 다섯 번째 레코드까지의 결과를 얻으려면 Cursor 값 2와 Limit 값 3을 제공합니다.
• Bubble은 항목 #2부터 시작하여 3개 항목을 보냅니다.
• 또한 항목의 다음 페이지를 가져오기 위한 커서로 사용할 수 있는 remaining 값도 제공합니다.

 

4. Sorting (정렬)

버블에서 Do a search for와 마찬가지로 Data API도 선택한 매개변수에 따라 결과를 정렬하도록 설정할 수 있습니다.

정렬을 적용하려면 다음 두 매개변수를 사용합니다.

1. Sort_field: 정렬하려는 필드
2. Descending (true/false)

*다중 정렬 매개변수

additional_sort_fields를 사용하여 제약 조건에서 했던 것처럼, 첫 번째 정렬 이후에 하나 이상의 추가적 정렬을 적용할 수도 있습니다.

 

예를 들어, unit number를 기준으로 정렬한 다음,  unit name을 기준으로 정렬하려는 경우 매개변수는 다음과 같습니다.

additional_sort_fields

[ { "sort_field": "unit name", "descending": "false"}]