저는 Prisma Reviews를 운영하고 있습니다. 84개 플랫폼의 고객 리뷰를 하나의 JSON 형식으로 반환하는 작은 API입니다. 이 글은 제품에 관한 것이 아니라, 우리의 시간 대부분을 차지했던 세 가지 엔지니어링 문제에 관한 것입니다. 형태가 매우 다른 소스들에 맞는 스키마를 설계하는 것, 동일한 리뷰가 두 번 표시되지 않도록 ID의 안정성을 유지하는 것, 그리고 상류의 변경이 하류 클라이언트를 조용히 깨뜨리지 않도록 계약(contract)을 테스트하는 것입니다.
먼저 한 가지 짚고 넘어갈 점이 있는데, 이것이 다른 모든 것을 좌우합니다. 모든 리뷰 소스가 API인 것은 아닙니다. 84개 소스 중 59개는 공식 API를 제공합니다. 나머지 25개는 그렇지 않아서, 대신 공개 페이지나 피드를 읽어옵니다.
모든 소스가 API인 것은 아닙니다
저희 설정의 모든 플랫폼에는 세 가지 속성이 있습니다: 비즈니스가 어떻게 연결하는지, 답변을 게시할 수 있는지, 그리고 새 리뷰가 어떻게 도착하는지입니다. 84개 소스를 읽는 방식별로 분류하면 네 그룹이 됩니다:
| 그룹 | 소스 수 | 예시 |
|---|---|---|
| 공식 API, 비즈니스 자체 자격 증명 또는 OAuth | 50 | Google Business Profile(승인 대기 중), App Store, Google Play, Trustpilot(승인 대기 중), Judge.me, Yotpo, eBay, Wix, WooCommerce, Shopware, Hostaway, Guesty 같은 숙박 관리 솔루션 |
| 공식 공개 API, 비즈니스 자격 증명 불필요 | 9 | Steam, Etsy, Salesforce AppExchange, Atlassian Marketplace, VS Code Marketplace, Open VSX, JetBrains Marketplace, Thunderbird Add-ons, Viator |
| API 없음: 공개 페이지 또는 피드 | 3 | Shopify App Store(HTML 리뷰 페이지), WordPress.org(RSS 리뷰 피드), Apple Podcasts(공개 리뷰 피드) |
| API 없음: 유료 데이터 제공업체 | 22 | Google Maps, Yelp, Tripadvisor, Booking.com, Facebook, Airbnb, Expedia, Capterra, OpenTable |

이 그룹들은 API 설계에 영향을 미치는 여러 면에서 차이가 납니다:
- 인증. 첫 번째 그룹은 OAuth 흐름이나 비즈니스가 붙여넣는 키가 필요합니다. 나머지 세 그룹은 리스팅의 공개 URL만 있으면 됩니다.
- 답변. 84개 소스 중 제3자가 답변을 게시할 수 있는 곳은 25곳뿐이며, 그중 Google Business Profile과 Trustpilot 두 곳은 아직 플랫폼의 접근 승인을 기다리는 중입니다. API가 있다고 충분하지 않습니다. Atlassian의 답변 엔드포인트는 이제
410 API_DEPRECATED로 응답하고, Microsoft Store의 답변 API는 Microsoft 측에서 고장난 상태라 두 플랫폼 모두 읽기 전용입니다. - 비용과 주기. 공식 API는 호출당 비용이 들지 않으므로 자주 확인합니다. 데이터 제공업체를 통한 읽기는 리뷰당 과금되며, 일부 제공업체는 실행당 새로 나온 모든 데이터에 대해 요금을 청구하기 때문에 이런 소스는 하루에 한 번 확인합니다.
- API가 없는 이유. Expedia의 답변 기능이 있는 파트너 API는 풀 채널 매니저에게만 열려 있으며, 우리는 거절당했습니다. Airbnb의 API는 초대받은 경우에만 사용할 수 있습니다. Shopify에는 리뷰 API가 없어서 앱 개발자가 자체 대시보드에서 답변합니다.
일부 플랫폼은 두 번 등장합니다. Airbnb와 Booking.com 리뷰는 공개 페이지(읽기 전용)에서 올 수도 있고, 답변을 허용하는 숙박 관리 솔루션의 공식 API를 통해서도 올 수 있습니다. 아래 필드 중 하나가 존재하는 이유가 바로 이것입니다.
모든 소스를 위한 하나의 스키마
모든 소스의 모든 리뷰는 동일한 14개 필드를 가지며, 그중 어느 것도 항상 존재합니다. 플랫폼이 데이터를 제공하지 않으면 해당 필드는 누락되는 것이 아니라 null입니다. 누락된 키와 null은 사람에게는 같은 의미지만 타입이 지정된 클라이언트에게는 다르며, "항상 존재" 방식은 테스트하기 쉽습니다.
{
"id": "rev_01KJ8Q2M4T7HX3VB9CWD6NRZ5E",
"platform": "google",
"location_id": "loc_01KJ8P9W2C4D6F8G0H2J4K6M8N",
"rating": 4,
"title": null,
"text": "Great flat white, a bit slow at lunchtime.",
"author": "Marta G.",
"language": "en",
"url": null,
"source": null,
"created_at": "2026-10-19T12:41:07.000Z",
"updated_at": "2026-10-19T12:41:07.000Z",
"deleted_at": null,
"reply": null
}rating은 1부터 5까지의 정수 또는 null입니다. Booking.com은 10점 만점이므로 2로 나눈 뒤 반올림하고 1-5 범위로 조정합니다. Steam에는 별점이 없고 "추천" 또는 "비추천"만 있으며, 이를 각각 5와 1로 매핑합니다. 일부 소스는 별점 없이 리뷰를 작성하는 것을 허용하며, 이 경우 필드는 null입니다. 우리는 절대 0을 쓰지 않습니다. 0은 실제 점수처럼 보이고 평균을 끌어내립니다.
text와 title은 null일 수 있습니다. 별점만 있는 리뷰는 앱 스토어에서 흔하며, 제목이 있는 플랫폼은 일부뿐입니다. 우리는 첫 문장에서 제목을 만들어내지 않습니다.
url은 읽기 전용 플랫폼에서 특별한 의미를 가집니다. 답변을 게시할 수 없을 때 url은 비즈니스가 수동으로 답변할 수 있는 위치입니다. 클라이언트가 그래도 답변을 시도하면 오류에 동일한 URL이 포함됩니다.
source는 애그리게이터 때문에 존재합니다. Viator는 Viator에서 작성된 리뷰와 Tripadvisor에서 작성된 리뷰를 모두 반환합니다. 숙박 관리 솔루션은 하나의 연결을 통해 Airbnb, Booking.com, Vrbo 리뷰를 반환합니다. platform은 리뷰가 어떤 연결을 통해 왔는지를 말하고, source는 어떤 사이트에 작성되었는지를 말합니다.
created_at과 updated_at은 분리되어 있습니다. 사람들이 리뷰를 수정하기 때문입니다. 별점 1개짜리 리뷰를 수정해서 4개짜리로 만든 것은 새 행이 아니라 업데이트로 처리되어야 합니다.
reply는 문자열이 아니라 상태를 가진 객체입니다. 상태는 published, queued, failed, unknown입니다. 마지막 것은 설명이 필요합니다. 때때로 플랫폼으로의 요청이 나갔는데 응답이 돌아오지 않고, 플랫폼에서 답변을 다시 읽어올 방법이 없는 경우가 있습니다. 재시도하면 비즈니스 명의로 동일한 답변이 두 번 게시될 수 있습니다. 그래서 우리는 중단하고 unknown으로 표시한 뒤, 클라이언트에게 다시 게시하기 전에 플랫폼을 확인하라고 알려줍니다. "우리는 모른다"고 말하는 상태가 추측보다 더 유용합니다.

답변 길이 제한은 답변이 대기열에 들어가기 전에 플랫폼별로 확인됩니다: Google Business Profile은 4,096바이트, Google Play는 350자, eBay는 80자입니다. 이모지는 한 글자이지만 4바이트이므로, 문자 제한에는 코드 포인트를, 바이트 제한에는 바이트를 계산합니다.
안정적인 ID와 중복 제거
중복은 클라이언트가 가장 먼저 알아차리는 버그입니다. 우리의 규칙은 간단합니다. 각 커넥터는 모든 리뷰에 대해 플랫폼 고유의 ID를 반환해야 하고, 데이터베이스에는 (location_id, external_id)에 대한 유니크 인덱스가 있습니다. 동일한 리뷰의 두 번째 동기화는 삽입이 아니라 업데이트입니다. 위치도 마찬가지로 (connection_id, external_id)에 유니크 인덱스가 있습니다.
어려운 점은 "플랫폼 고유의 ID"가 항상 존재하지는 않는다는 것입니다:
- Etsy 리뷰에는 자체 ID가 없습니다. 각 리뷰는 정확히 하나의 거래에 속하므로, 거래 ID가 곧 리뷰 ID입니다.
- WordPress.org는 피드에 리뷰 ID를 제공하지 않습니다. 각 리뷰는 포럼 토픽이므로 토픽 슬러그를 사용합니다.
- Shopify App Store 페이지는 HTML에 리뷰 콘텐츠 ID를 담고 있습니다. 페이지 리디자인으로 바뀔 수 있다는 점을 알면서도 이에 의존합니다.
- Google Play에는 실제 ID가 있지만, API는 최근 7일 이내에 생성되거나 수정된 리뷰만 반환합니다. 저장된 히스토리는 우리 것이며 다시 읽어올 수 없습니다.
클라이언트는 플랫폼 ID를 기본 키로 보지 않습니다. 클라이언트는 타입 접두사와 시간 순서 본문을 가진 우리 고유의 ID를 받습니다(rev_01KJ…, loc_01KJ…, req_01KJ…). 접두사는 로그에서 잘못 배치된 ID를 명확하게 드러내고, 순서는 페이지네이션에 도움이 됩니다. 커서가 마지막 항목의 타임스탬프와 ID를 인코딩하므로 새 리뷰가 도착하더라도 페이지 경계가 그대로 유지됩니다.
재연결. 비즈니스가 계정 연결을 해제했다가 일주일 뒤 다시 연결하는 경우가 있습니다. 새 위치를 만들면 모든 리뷰가 중복됩니다. 대신, 30일 이내에 연결이 해제되었고 동일한 외부 ID를 가진 위치는 재활성화됩니다. 같은 ID, 중복 없음입니다.
삭제. 플랫폼에서 삭제된 리뷰는 그냥 더 이상 나타나지 않습니다. 아무것도 알려주지 않습니다. 84개 소스 중 60개는 전체 히스토리를 읽을 수 있으므로 주기적으로 다시 읽어서(Google Business Profile은 약관상 콘텐츠를 30일 이상 미확인 상태로 둘 수 없으므로 25일마다, 대부분의 다른 소스는 매주) 플랫폼이 더 이상 반환하지 않는 리뷰에 deleted_at을 표시하고 review.deleted 웹훅을 보냅니다. 핵심 안전장치는 이것입니다. 타임아웃이나 페이지 제한 때문에 읽기가 중간에 끊겼다면 아무것도 표시하지 않습니다. "내가 못 봤다"를 "사라졌다"로 취급하면 실제 리뷰가 삭제됩니다. Google Play는 7일 제한 때문에 제외됩니다.
OpenAPI 스펙에 대한 계약 테스트
계약은 18개 경로, 30개 스키마, 9개 웹훅 이벤트를 가진 OpenAPI 3.1 문서입니다. 두 종류의 테스트가 이를 신뢰할 수 있게 유지합니다.
첫 번째는 저렴하고 모든 커밋에서 실행됩니다. 스펙의 enum은 코드와 정확히 일치해야 합니다. 스펙의 플랫폼 ID는 플랫폼 설정의 목록과 같아야 하고, 스펙의 웹훅 이벤트는 코드가 발생시킬 수 있는 이벤트 타입과 같아야 합니다. 생성된 클라이언트는 모르는 enum 값을 거부하므로, 코드에는 추가됐지만 스펙에는 없는 플랫폼은 첫 동기화에서 그 클라이언트들을 깨뜨릴 것입니다.
두 번째는 테스트 모드입니다. API 키는 두 종류, 즉 pk_live_…와 pk_test_…가 있으며 동일한 서버에 대해 작동합니다. 테스트 키는 모든 플랫폼을 테스트 커넥터로 라우팅합니다. 실제와 같은 형태의 결정론적 샘플 위치와 리뷰(Google의 카페, App Store의 앱, Booking.com의 호텔), 어디에도 게시되지 않고 승인만 되는 답변, 그리고 문서가 약속하는 대로 읽기 전용 플랫폼에서는 모든 리뷰에 url이 있습니다. 누구나 실제 계정에 손대지 않고 쓰기 경로를 포함한 전체 계약을 실행할 수 있습니다.
아래 예시는 스펙에 있는 것들로, URL은 example.com으로 대체되었습니다. 목록 요청:
GET /v1/reviews?platform=google&limit=1
Authorization: Bearer pk_test_…는 앞서 본 리뷰를 data 안에, 그리고 next_cursor와 함께 반환합니다. 답변을 지원하는 플랫폼에 대한 답변은 202로 승인되며, 리뷰는 대기열에 답변을 넣은 상태로 돌아옵니다(다른 필드는 생략):
POST /v1/reviews/rev_01KJ8Q2M4T7HX3VB9CWD6NRZ5E/reply
Authorization: Bearer pk_test_…
Content-Type: application/json
{ "text": "Thanks Marta! We have added a second barista at lunch." }{
"id": "rev_01KJ8Q2M4T7HX3VB9CWD6NRZ5E",
"platform": "google",
"reply": {
"text": "Thanks Marta! We have added a second barista at lunch.",
"created_at": null,
"status": "queued",
"error": null
}
}흥미로운 경우는 실패입니다. 모든 오류는 동일한 형태(type, code, message, retryable, request_id, docs_url)를 가지며, 일부 코드는 클라이언트가 대응할 수 있는 필드를 추가합니다. Yelp 리뷰에 답변하면 422가 반환됩니다:
{
"error": {
"type": "invalid_request_error",
"code": "reply_not_supported",
"message": "Yelp has no reply API for third parties, so Prisma only reads its reviews. Answer this one on the platform: https://example.com/biz/example-cafe-madrid",
"retryable": false,
"request_id": "req_01KJ8T3C5D7E9F1G3H5J7K9M1N",
"docs_url": "https://example.com/docs/errors#reply_not_supported",
"platform": "yelp",
"url": "https://example.com/biz/example-cafe-madrid"
}
}플랫폼 제한을 초과하는 답변 역시 422를 반환하며, code: "reply_too_long", platform: "google_play", max_length: 350이 함께 옵니다. 클라이언트는 message가 아니라 code를 기준으로 분기해야 합니다. message는 사람을 위한 것이며 언제든 바뀔 수 있습니다.
동일한 형태가 실제 트래픽에서도 유지됩니다. 다음은 키 없는 요청에 대한 프로덕션의 실제 응답입니다(헤더는 축약, docs URL은 대체):
HTTP/1.1 401 Unauthorized
Content-Type: application/json
Request-Id: req_01K6VVGDM8CFFJEQ3MNWWR582S
{"error":{"type":"authentication_error","code":"missing_api_key","message":"Send your API key as \"Authorization: Bearer pk_live_…\".","retryable":false,"request_id":"req_01K6VVGDM8CFFJEQ3MNWWR582S","docs_url":"https://example.com/docs/errors#missing_api_key"}}본문의 request_id는 Request-Id 헤더와 일치합니다. 각 작업에 대해 우리는 상태 코드, 본문이 스키마에 대해 유효한지(모든 14개 리뷰 필드 존재, 선언된 곳에는 null 허용 타입), 모든 non-2xx 응답의 오류 형태, 그리고 성공 시 Request-Id와 속도 제한 헤더를 검사합니다.
Apidog CLI로 동일한 검사 실행하기
동일한 검사는 OpenAPI 파일을 제공하는 모든 API에 적용할 수 있습니다. Apidog CLI가 스펙을 가져오고, Claude Code 같은 코딩 에이전트가 테스트 케이스를 작성하고 실행합니다. 한 번만 설정하면 됩니다:
npm install -g apidog-cli@latest
apidog login --with-token <YOUR_TOKEN>
apidog skill install
그다음 에이전트에 프롬프트 하나를 주면 됩니다:
Import ./openapi.json into Apidog project <projectId>. Create test cases for the
list reviews and reply endpoints that assert the status code, that the body
validates against its schema with all 14 review fields present, and that the
Request-Id header is set. Add a case that replies to a Yelp review and expects
422 with code reply_not_supported. Run them against the test environment and
summarize any failures.에이전트는 스펙을 가져오고, 테스트 케이스 스키마를 읽고, 페이로드를 검증하고, 케이스를 만들어 실행합니다:
apidog import --project <projectId> --format openapi --file ./openapi.json
apidog cli-schema get test-case-create
apidog cli-schema validate test-case-create --file case.json
apidog test-case create --project <projectId> --file case.json
apidog run --test-case <caseId> --project <projectId> -e <envId> -r cli,junit
junit 리포터는 CI가 읽을 수 있는 파일을 작성하므로, 동일한 실행으로 모든 풀 리퀘스트를 게이트할 수 있습니다. 파이프라인 설정은 Apidog CLI CI/CD 가이드에서 다룹니다.
교훈
"API가 있다"와 "답변할 수 있다"를 별개의 속성으로 모델링하라. Atlassian과 Microsoft는 API가 존재하더라도 답변을 받지 않을 수 있음을 보여줍니다. 두 가지를 하나의 플래그로 처리하면 우리가 실제로 제공할 수 없는 답변 기능을 약속하는 셈이 됩니다.
첫 답변이 나가기 전에 unknown 답변 상태를 계획하라. 불확실성을 인정하는 상태는 enum 값 하나의 비용이 들지만, 중복된 공개 답변은 고객의 신뢰라는 대가를 치르게 됩니다.
플랫폼 ID가 존재하고 안정적일 것이라고 믿지 말라. 커넥터별로 ID가 어디서 오는지, 무엇이 그것을 바꿀 수 있는지 기록해 두어야 합니다.
코드를 스펙에 맞춰 테스트하는 것만이 아니라, 스펙을 코드에 맞춰 테스트하라. enum 테스트는 십 줄 정도의 코드지만, 생성된 클라이언트에 가장 큰 피해를 주는 실패를 방어해 줍니다.
