Cách Chuẩn Hóa Dữ Liệu Từ 84 API Về Một Schema Đ Chung (Và Kiểm Thử Hợp Đồng)

Chuẩn hóa các bài đánh giá từ 84 nền tảng — 59 có API chính thức và 25 không có — về một schema duy nhất, với ID ổn định, khử trùng lặp và kiểm thử hợp đồng (contract tests) dựa trên đặc tả OpenAPI.

Francisco Garcia Domene

Francisco Garcia Domene

16 tháng 11 2026

Cách Chuẩn Hóa Dữ Liệu Từ 84 API Về Một Schema Đ Chung (Và Kiểm Thử Hợp Đồng)

Apidog cho doanh nghiệp

Triển khai tại chỗ

SSO & RBAC

Tuân thủ SOC 2

Khám phá Apidog Enterprise

Tôi vận hành Prisma Reviews, một API nhỏ trả về đánh giá của khách hàng từ 84 nền tảng dưới một định dạng JSON thống nhất. Bài viết này không nói về sản phẩm, mà nói về ba bài toán kỹ thuật chiếm phần lớn thời gian của chúng tôi: thiết kế một schema phù hợp với các nguồn dữ liệu có hình dạng rất khác nhau, giữ cho ID ổn định để cùng một đánh giá không bao giờ xuất hiện hai lần, và kiểm thử hợp đồng (contract) để một thay đổi phía nguồn không âm thầm làm hỏng các client phía dưới.

Trước tiên, một điều quan trọng vì nó định hình tất cả những gì còn lại: không phải nguồn đánh giá nào cũng là API. Trong 84 nguồn của chúng tôi, 59 nguồn có API chính thức. 25 nguồn còn lại thì không, và chúng tôi đọc các trang công khai hoặc feed của họ thay thế.

Không phải nguồn nào cũng là API

Mỗi nền tảng trong cấu hình của chúng tôi có ba thuộc tính: cách một doanh nghiệp kết nối với nó, liệu chúng tôi có thể đăng câu trả lời hay không, và cách các đánh giá mới được đưa đến cho chúng tôi. Phân loại 84 nguồn theo cách chúng tôi đọc dữ liệu cho ra bốn nhóm:

NhómSố nguồnVí dụ
API chính thức, dùng thông tin xác thực hoặc OAuth của doanh nghiệp50Google Business Profile (đang chờ phê duyệt quyền truy cập), App Store, Google Play, Trustpilot (đang chờ phê duyệt), Judge.me, Yotpo, eBay, Wix, WooCommerce, Shopware, các phần mềm quản lý chỗ nghỉ như Hostaway và Guesty
API công khai chính thức, không cần thông tin xác thực của doanh nghiệp9Steam, Etsy, Salesforce AppExchange, Atlassian Marketplace, VS Code Marketplace, Open VSX, JetBrains Marketplace, Thunderbird Add-ons, Viator
Không có API: đọc trang công khai hoặc feed3Shopify App Store (trang HTML chứa đánh giá), WordPress.org (feed RSS đánh giá), Apple Podcasts (feed đánh giá công khai)
Không có API: dùng nhà cung cấp dữ liệu trả phí22Google Maps, Yelp, Tripadvisor, Booking.com, Facebook, Airbnb, Expedia, Capterra, OpenTable
Biểu đồ cột của 84 nguồn đánh giá: 50 nguồn có API chính thức dùng thông tin xác thực của doanh nghiệp, 9 nguồn có API công khai, 3 nguồn đọc từ trang công khai hoặc feed, 22 nguồn đọc qua nhà cung cấp dữ liệu trả phí

Các nhóm này khác nhau theo những cách mà ảnh hưởng trực tiếp đến thiết kế API:

Một số nền tảng xuất hiện hai lần. Đánh giá Airbnb và Booking.com có thể đến từ một trang công khai (chỉ đọc), hoặc qua API chính thức của một phần mềm quản lý chỗ nghỉ, vốn cho phép trả lời. Đó là lý do tồn tại một trong các trường bên dưới.

Một schema cho tất cả

Mọi đánh giá, từ mọi nguồn, đều có cùng 14 trường, và tất cả đều luôn luôn có mặt. Khi một nền tảng không cung cấp thông tin nào đó, trường đó là null, chứ không bao giờ bị thiếu. Một khóa bị thiếu và một giá trị null có nghĩa giống nhau đối với con người, nhưng không đối với một client có kiểu dữ liệu chặt, và "luôn có mặt" thì dễ kiểm thử.

{
  "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 là số nguyên từ 1 đến 5, hoặc null. Booking.com chấm điểm thang 10, nên chúng tôi chia hai, làm tròn và giới hạn trong khoảng 1-5. Steam không có sao, chỉ có "recommend" hoặc "not recommend", mà chúng tôi ánh xạ thành 5 và 1. Một số nguồn cho phép đánh giá không có điểm số, và khi đó trường này là null. Chúng tôi không bao giờ ghi giá trị 0: nó trông giống một điểm số thực và kéo điểm trung bình xuống.

text và title có thể là null. Đánh giá chỉ có điểm số rất phổ biến trên các cửa hàng ứng dụng, và chỉ một số nền tảng có tiêu đề. Chúng tôi không tự bịa tiêu đề từ câu đầu tiên.

url mang một ý nghĩa cụ thể trên các nền tảng chỉ đọc. Khi chúng tôi không thể đăng câu trả lời, url là nơi doanh nghiệp có thể trả lời thủ công. Nếu client vẫn cố trả lời, thông báo lỗi sẽ mang theo chính URL đó.

source tồn tại là vì các aggregator. Viator trả về các đánh giá viết trên Viator và cả trên Tripadvisor. Một phần mềm quản lý chỗ nghỉ trả về các đánh giá Airbnb, Booking.com và Vrbo qua một kết nối duy nhất. platform cho biết đánh giá đi qua kết nối nào; source cho biết nó được viết trên trang nào.

created_at và updated_at là hai trường riêng vì người dùng có thể chỉnh sửa đánh giá. Một đánh giá một sao được sửa thành bốn sao phải là một bản cập nhật, chứ không phải một dòng mới.

reply là một object có trạng thái, không phải một chuỗi. Trạng thái là published, queued, failed hoặc unknown. Trạng thái cuối cùng cần giải thích. Đôi khi yêu cầu gửi đến nền tảng đã đi ra nhưng không có phản hồi nào quay lại, và nền tảng không có cách để đọc lại câu trả lời. Thử lại có thể đăng cùng một câu trả lời hai lần, dưới tên của doanh nghiệp. Vì vậy chúng tôi dừng lại, đánh dấu là unknown, và yêu cầu client kiểm tra nền tảng trước khi đăng lại. Một trạng thái nói rằng "chúng tôi không biết" hữu ích hơn một phỏng đoán.

Sơ đồ các trạng thái trả lời: một câu trả lời được chấp nhận với 202 và đưa vào hàng đợi, sau đó kết thúc ở trạng thái published, failed hoặc unknown

Giới hạn độ dài câu trả lời được kiểm tra theo từng nền tảng trước khi câu trả lời được đưa vào hàng đợi: 4.096 byte trên Google Business Profile, 350 ký tự trên Google Play, 80 trên eBay. Một emoji là một ký tự nhưng chiếm bốn byte, nên chúng tôi đếm code point cho giới hạn ký tự và đếm byte cho giới hạn byte.

ID ổn định và khử trùng lặp

Dữ liệu trùng lặp là lỗi mà client nhận thấy đầu tiên. Quy tắc của chúng tôi rất đơn giản: mỗi connector phải trả về ID riêng của nền tảng cho mọi đánh giá, và cơ sở dữ liệu có một unique index trên (location_id, external_id). Một lần đồng bộ thứ hai của cùng một đánh giá là một bản cập nhật, không bao giờ là một bản ghi mới. Vị trí (location) hoạt động theo cách tương tự, với unique index trên (connection_id, external_id).

Phần khó là "ID riêng của nền tảng" không phải lúc nào cũng tồn tại:

Client không bao giờ thấy ID của nền tảng làm khóa chính. Họ nhận ID do chúng tôi tự tạo, có tiền tố kiểu dữ liệu và phần thân được sắp xếp theo thời gian (rev_01KJ…, loc_01KJ…, req_01KJ…). Tiền tố giúp nhận ra ngay một ID bị đặt sai vị trí trong log, và thứ tự sắp xếp hỗ trợ phân trang: cursor mã hóa timestamp và ID của mục cuối cùng, nên ranh giới trang không bị xê dịch khi có đánh giá mới xuất hiện.

Kết nối lại. Một doanh nghiệp ngắt kết nối tài khoản và kết nối lại sau một tuần. Việc tạo các location mới sẽ nhân đôi mọi đánh giá. Thay vào đó, một location bị ngắt kết nối dưới 30 ngày với cùng external ID sẽ được kích hoạt lại: giữ nguyên ID, không có đánh giá trùng lặp.

Xóa đánh giá. Một đánh giá bị gỡ khỏi nền tảng đơn giản là ngừng xuất hiện. Không có gì báo cho bạn biết. Với 60 trong 84 nguồn, chúng tôi có thể đọc toàn bộ lịch sử, nên chúng tôi đọc lại định kỳ (mỗi 25 ngày với Google Business Profile, vì điều khoản của họ không cho phép chúng tôi giữ nội dung chưa xác nhận quá 30 ngày; hàng tuần với phần lớn nguồn khác) và đánh dấu các đánh giá mà nền tảng không còn trả về bằng deleted_at, kèm một webhook review.deleted. Biện pháp bảo vệ then chốt: nếu một lần đọc bị dừng sớm, do timeout hoặc do giới hạn số trang, chúng tôi không đánh dấu gì cả. Xem "tôi không thấy nó" là "nó đã bị xóa" sẽ xóa nhầm những đánh giá có thật. Google Play bị loại trừ vì cửa sổ bảy ngày của nó.

Kiểm thử hợp đồng dựa trên đặc tả OpenAPI

Hợp đồng là một tài liệu OpenAPI 3.1 với 18 path, 30 schema và 9 sự kiện webhook. Hai loại kiểm thử giúp nó luôn chính xác.

Loại đầu tiên rẻ và chạy trên mỗi commit: các enum trong đặc tả phải khớp chính xác với mã nguồn. Các ID nền tảng trong đặc tả phải bằng với danh sách trong cấu hình nền tảng, và các sự kiện webhook trong đặc tả phải bằng với các loại sự kiện mà mã nguồn có thể phát ra. Các client được sinh tự động sẽ từ chối các giá trị enum mà chúng không biết, nên một nền tảng được thêm vào mã nhưng không có trong đặc tả sẽ làm hỏng những client đó ngay lần đồng bộ đầu tiên.

Loại thứ hai là chế độ kiểm thử (test mode). Khóa API có hai loại, pk_live_… và pk_test_…, cùng指向 cùng một máy chủ. Một khóa test sẽ định tuyến mọi nền tảng đến một connector kiểm thử: các location và đánh giá mẫu xác định, có hình dạng giống thật (một quán cà phê trên Google, một ứng dụng trên App Store, một khách sạn trên Booking.com), các câu trả lời được chấp nhận nhưng không bao giờ được đăng ở đâu đó, và trên các nền tảng chỉ đọc, mọi đánh giá đều có một url, vì tài liệu hứa hẹn trường này. Bất kỳ ai cũng có thể chạy toàn bộ hợp đồng, bao gồm cả các path ghi, mà không chạm vào một tài khoản thật nào.

Các ví dụ dưới đây là những ví dụ nằm trong đặc tả, với URL được thay bằng example.com. Một yêu cầu lấy danh sách:

GET /v1/reviews?platform=google&limit=1
Authorization: Bearer pk_test_…

trả về đánh giá đã trình bày ở trên bên trong data, kèm một next_cursor. Một câu trả lời cho nền tảng hỗ trợ trả lời được chấp nhận với 202, và đánh giá quay lại với câu trả lời đang trong hàng đợi (các trường khác bị lược bỏ):

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
  }
}

Những trường hợp thú vị là các trường hợp lỗi. Mọi lỗi có cùng cấu trúc (type, code, message, retryable, request_id, docs_url), và một số mã thêm các trường mà client có thể hành động dựa trên đó. Trả lời một đánh giá Yelp trả về 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"
  }
}

Một câu trả lời vượt giới hạn của nền tảng cũng trả về 422, với code: "reply_too_long", platform: "google_play" và max_length: 350. Client nên rẽ nhánh dựa trên code, không bao giờ dựa trên message: message dành cho con người và có thể thay đổi.

Cùng cấu trúc đó vẫn đúng trên lưu lượng thực. Đây là một phản hồi thật từ môi trường production cho một yêu cầu không có khóa (đã lược bớt header, thay URL tài liệu):

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 trong body khớp với header Request-Id. Với mỗi operation, chúng tôi kiểm tra mã trạng thái, rằng body hợp lệ theo schema của nó (cả 14 trường đánh giá đều có mặt, kiểu nullable ở đúng nơi đã khai báo), cấu trúc lỗi trên mọi phản hồi không phải 2xx, và các header Request-Id và rate-limit khi thành công.

Chạy các kiểm tra tương tự với Apidog CLI

Những kiểm tra này hoạt động với mọi API đi kèm một file OpenAPI. Apidog CLI nhập đặc tả, và một coding agent như Claude Code viết và chạy các test case. Cài đặt một lần:

npm install -g apidog-cli@latest
apidog login --with-token <YOUR_TOKEN>
apidog skill install
Terminal hiển thị việc thiết lập Apidog CLI và lệnh apidog import đang tải một file OpenAPI vào project

Sau đó đưa cho agent một prompt duy nhất:

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.

Agent nhập đặc tả, đọc schema của test case, xác thực payload, tạo test case và chạy nó:

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
Terminal hiển thị Apidog CLI xác thực file test case, tạo test case và chạy nó với reporter CLI và JUnit

Reporter junit ghi ra một file mà CI của bạn có thể đọc, nên cùng một lần chạy đó có thể làm điều kiện chặn cho mọi pull request. Hướng dẫn CI/CD với Apidog CLI trình bày chi tiết cách thiết lập pipeline.

Bài học rút ra

Mô hình hóa "có API" và "có thể trả lời" thành hai thuộc tính riêng biệt. Atlassian và Microsoft cho thấy một API có thể tồn tại nhưng vẫn không nhận câu trả lời. Dùng một cờ duy nhất cho cả hai sẽ hứa hẹn điều mà chúng tôi không thể đáp ứng.

Hãy thiết kế trạng thái trả lời unknown trước khi câu trả lời đầu tiên được gửi đi. Một trạng thái thừa nhận sự không chắc chắn chỉ tốn một giá trị enum; một câu trả lời công khai bị trùng lặp lại làm mất lòng tin của khách hàng.

Đừng tin rằng ID nền tảng luôn tồn tại hoặc luôn ổn định. Hãy ghi lại, cho từng connector, ID đến từ đâu và điều gì có thể làm thay đổi nó.

Kiểm thử đặc tả dựa trên mã nguồn, chứ không chỉ mã nguồn dựa trên đặc tả. Bài kiểm tra enum chỉ khoảng mười dòng mã, nhưng nó bảo vệ khỏi loại lỗi gây tổn hại nhất cho các client được sinh tự động.

Thực hành thiết kế API trong Apidog

Khám phá cách dễ dàng hơn để xây dựng và sử dụng API