Sebastian Petrus

Posted on Jun 2 • Originally published at apidog.com

Bruno: Thiết Kế API Trước Hay Yêu Cầu API Trước? Lựa Chọn Công Cụ Thiết Kế API Phù Hợp

Bruno ưu tiên request trước ư? Đúng vậy. Bruno được xây dựng xoay quanh việc tổng hợp, tổ chức và gửi HTTP request. Bạn tạo collection, thêm request, lưu chúng trong các tệp .bru, chạy request, rồi quản lý phiên bản toàn bộ trong Git. Cách làm này nhanh, thân thiện với Git và rất phù hợp khi bạn đang khám phá hoặc kiểm thử một API đã tồn tại.

Dùng thử Apidog ngay hôm nay

Nhưng “ưu tiên request” và “ưu tiên thiết kế” giải quyết hai bài toán khác nhau:

Ưu tiên request hỏi: làm thế nào để gọi endpoint này?
Ưu tiên thiết kế hỏi: endpoint này nên trông như thế nào trước khi bất kỳ ai viết code server?

Khoảng cách giữa hai câu hỏi này thường xuất hiện khi nhóm bắt đầu xây dựng API mới, API nội bộ dùng chung, hoặc API công khai. Bài viết này phân tích sự đánh đổi giữa mô hình ưu tiên request của Bruno và quy trình ưu tiên thiết kế dựa trên OpenAPI, đồng thời chỉ ra khi nào nên dùng từng cách.

Ưu tiên request so với ưu tiên thiết kế: tóm tắt nhanh

Hai phương pháp này không nhất thiết đối lập nhau. Chúng là hai điểm xuất phát khác nhau trong vòng đời API.

Khía cạnh	Ưu tiên request (Bruno)	Ưu tiên thiết kế (chuẩn OpenAPI)
Thành phần khởi đầu	Một request có thể gửi ngay	Một hợp đồng API, thường là OpenAPI spec
Phù hợp nhất cho	Khám phá và kiểm thử API hiện có	Thiết kế API mới hoặc API dùng chung trước khi viết code
Nguồn đáng tin cậy	Collection request	Spec
Review chéo nhóm	Sau khi endpoint đã tồn tại	Trước khi viết code server
Giao diện thiết kế trực quan	Không có theo mặc định	Trình thiết kế trực quan + trình chỉnh sửa schema
Rủi ro sai lệch	Collection có thể lạc hậu so với API thực tế	Spec đóng vai trò hợp đồng duy nhất
Git workflow	Mạnh với file `.bru` dạng plain text	Mạnh khi công cụ đồng bộ spec với Git

Cách chọn đơn giản:

API đã tồn tại và bạn cần gọi, debug, kiểm thử: ưu tiên request thường hiệu quả hơn.
API chưa tồn tại hoặc cần nhiều nhóm thống nhất trước: ưu tiên thiết kế thường an toàn hơn.

Mô hình ưu tiên request của Bruno

Bruno làm tốt một việc rất cụ thể: lưu trữ và chạy request dưới dạng tệp .bru văn bản thuần túy trong thư mục bạn sở hữu. Không bắt buộc tài khoản cloud, không đồng bộ độc quyền, không phải đưa collection ra khỏi repo.

Đây là lý do Bruno phù hợp với các nhóm muốn API client hoạt động giống phần còn lại của codebase. Nó cũng là nền tảng của quy trình làm việc API Git-native mà nhiều nhóm áp dụng.

Bruno nổi bật trong các tình huống sau:

Khám phá API hiện có: trỏ request vào một service đang chạy, gửi request, xem response, chỉnh sửa, lặp lại.
Làm việc local và thân thiện với Git: request nằm trong repo, diff dễ đọc hơn so với định dạng nhị phân hoặc đồng bộ cloud.
Kiểm thử hằng ngày: dùng pre-request script, post-request script, assertion và biến môi trường.
Tránh lock-in: file nằm trong máy và repo của bạn.

Một workflow điển hình với Bruno thường là:

Tạo collection trong repo.
Thêm request cho từng endpoint.
Cấu hình environment như dev, staging, prod.
Viết assertion cho response quan trọng.
Commit file .bru cùng với thay đổi code liên quan.
Review request trong pull request.

Nếu công việc chính của bạn là sử dụng và xác minh API đã tồn tại, mô hình ưu tiên request là con đường trực tiếp. Chúng tôi cũng đã đề cập điều này trong phân tích các lựa chọn thay thế Bruno.

Chi phí của việc không có lớp thiết kế hoặc hợp đồng

Vấn đề bắt đầu xuất hiện khi API chưa tồn tại, hoặc khi nhiều nhóm cần thống nhất trước về hình dạng API.

1. Không có thiết kế tài nguyên ở cấp hợp đồng

Công cụ ưu tiên request biểu diễn API thông qua các request cụ thể. Điều đó hữu ích khi endpoint đã có, nhưng không đủ nếu bạn cần thiết kế:

resource model
request body schema
response schema
error format
authentication rule
versioning rule

Thiết kế bằng request có nghĩa là thiết kế bằng ví dụ. Ví dụ có thể giúp minh họa, nhưng không bắt buộc cấu trúc.

Ví dụ, một request mẫu có thể cho thấy response như sau:

{
  "id": "usr_123",
  "name": "Nguyen Van A",
  "email": "a@example.com"
}

Nhưng nó không trả lời đầy đủ các câu hỏi thiết kế:

id có bắt buộc không?
email có nullable không?
name có giới hạn độ dài không?
Response lỗi dùng format nào?
Endpoint này có phân trang không?

Với OpenAPI, các câu hỏi đó được đưa vào hợp đồng:

openapi: 3.1.0
info:
  title: Users API
  version: 1.0.0
paths:
  /users/{id}:
    get:
      summary: Lấy thông tin người dùng
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Người dùng tồn tại
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
        "404":
          description: Không tìm thấy người dùng
components:
  schemas:
    User:
      type: object
      required:
        - id
        - name
        - email
      properties:
        id:
          type: string
        name:
          type: string
        email:
          type: string
          format: email

2. Dễ sai lệch hợp đồng

Khi collection request là nguồn tham chiếu chính, nó chỉ phản ánh những gì ai đó đã từng gọi. API thực tế có thể thay đổi:

thêm field mới
bỏ parameter
đổi kiểu dữ liệu
thay đổi rule xác thực
đổi format lỗi

Collection có thể vẫn chạy được trong một số case, nhưng không còn mô tả đầy đủ API.

Quy trình dựa trên spec đảo ngược điều này:

Spec là hợp đồng.
Implementation được xây dựng theo spec.
Test, mock, docs và review bám theo spec.
Nếu implementation lệch spec, đó là lỗi cần xử lý.

3. Review chéo nhóm khó hơn trước khi viết code

Review một thư mục request cho biết API đang được gọi như thế nào. Nhưng nó không phải tài liệu khai báo rõ ràng để frontend, backend, QA và product cùng duyệt trước khi triển khai.

Với API dùng chung, review nên diễn ra trước khi code server được viết:

Backend đề xuất OpenAPI spec.
Frontend kiểm tra request/response có đủ dữ liệu không.
QA kiểm tra trạng thái lỗi và edge case.
Product xác nhận hành vi nghiệp vụ.
Nhóm chốt contract.
Backend và frontend triển khai song song.

Không có contract hạng nhất, bước review này thường chậm hơn và dễ phụ thuộc vào trao đổi thủ công.

Điều này không làm Bruno trở thành công cụ kém. Nó chỉ cho thấy Bruno là công cụ ưu tiên request, và sẽ kém phù hợp hơn nếu bạn dùng nó cho công việc ưu tiên thiết kế.

Khi ưu tiên thiết kế giành chiến thắng

Ưu tiên thiết kế phát huy hiệu quả nhất trong ba tình huống sau.

1. API mới hoàn toàn

Khi chưa có endpoint nào tồn tại, spec chính là thiết kế. Bạn có thể định nghĩa trước:

path
method
request body
response body
schema dùng lại
error format
auth requirement

Sau đó, nhóm có thể tạo mock, docs hoặc stub từ cùng một contract thay vì suy luận ngược từ các request sau này.

2. API có nhiều nhóm phụ thuộc

Khi backend và một hoặc nhiều nhóm client phải cùng làm việc, OpenAPI spec trở thành thỏa thuận chung.

Một quy trình thực tế:

Backend tạo draft spec.
Frontend review schema và bắt đầu tích hợp với mock.
QA viết test case dựa trên response và error contract.
Backend triển khai endpoint thật.
Các nhóm kiểm tra implementation so với spec.

Cách này giúp frontend không phải chờ endpoint thật mới bắt đầu làm việc.

3. API công khai

Với API công khai, tài liệu và độ ổn định là một phần của sản phẩm. Một contract được duy trì tốt giúp bạn:

tạo tài liệu tham khảo nhất quán
quản lý version rõ ràng
truyền đạt breaking change có chủ ý
giảm hiểu nhầm cho developer bên ngoài

Điểm chung: ưu tiên thiết kế thắng thế khi API là giao diện chia sẻ cần được thống nhất trước khi viết code, không chỉ là một service cần kiểm thử sau khi triển khai.

Apidog: ưu tiên thiết kế cộng với Chế độ Spec-First

Apidog được xây dựng theo hướng ưu tiên thiết kế. Điểm quan trọng là bạn vẫn có thể giữ workflow dựa trên OpenAPI và Git.

Trong cùng một dự án, bạn có thể làm việc theo hai cách:

Trình thiết kế trực quan: định nghĩa endpoint, request schema, response schema và component có thể tái sử dụng mà không cần viết tay YAML.
Chế độ Spec-First: chỉnh sửa OpenAPI trực tiếp bằng trình chỉnh sửa code, trong đó spec là nguồn đáng tin cậy.

Hai chế độ này được giữ đồng bộ. Điều đó cho phép:

backend engineer chỉnh sửa OpenAPI thô
product hoặc API designer xem và chỉnh trên giao diện trực quan
cả hai cùng làm việc trên một hợp đồng API

Workflow triển khai API theo hướng thiết kế

Một quy trình thực tế có thể như sau:

Tạo endpoint và schema trong trình thiết kế trực quan.
Kiểm tra OpenAPI spec ở Chế độ Spec-First.
Commit spec vào Git.
Review spec trong pull request.
Sau khi contract được duyệt, backend triển khai.
Frontend dùng mock hoặc contract để tích hợp song song.
Test implementation dựa trên contract đã chốt.

Chế độ Spec-First cũng hỗ trợ đồng bộ Git hai chiều: spec nằm trong repo của bạn dưới dạng một tệp thực, thay đổi có thể đi qua cả hai hướng, và thiết kế API được review giống như code.

Đây là thuộc tính Git-native mà người dùng Bruno đánh giá cao, nhưng được áp dụng cho hợp đồng API thay vì chỉ cho collection request. Cơ chế chi tiết có trong tài liệu Chế độ Spec-First.

Kết quả là một workflow bao phủ cả hai câu hỏi:

Trước khi code: contract nên trông như thế nào?
Sau khi endpoint chạy: request thực tế có tuân thủ contract không?

Để hiểu sâu hơn về điểm giao giữa hai mô hình này, xem spec-first vs design-first trong Apidog.

Cách chọn theo mức độ trưởng thành của nhóm

Đừng chọn công cụ chỉ theo sở thích. Hãy chọn theo vị trí của API trong vòng đời phát triển.

1. Nhóm solo hoặc nhóm nhỏ, chủ yếu dùng API có sẵn

Ưu tiên request thường là đủ.

Bạn cần:

gửi request nhanh
debug response
lưu collection trong Git
viết assertion cơ bản
chia sẻ request với đồng đội

Trong trường hợp này, mô hình local-first của Bruno rất hợp lý. Bạn không nhất thiết phải duy trì một contract chính thức nếu API không có nhiều bên phụ thuộc.

2. Nhóm đang phát triển và tự triển khai API

Đây là điểm chuyển đổi.

Khi nhóm thứ hai bắt đầu phụ thuộc vào endpoint của bạn, collection request không còn đủ. Bạn cần contract rõ ràng để giảm:

lỗi tích hợp
hiểu nhầm giữa frontend và backend
thay đổi API không được thông báo
review thủ công qua chat hoặc tài liệu rời rạc

Lúc này, OpenAPI spec bắt đầu tạo ra giá trị thực tế.

3. Tổ chức trưởng thành với API công khai hoặc nhiều API nội bộ

Ưu tiên thiết kế gần như trở thành yêu cầu bắt buộc.

Spec không chỉ là tài liệu kỹ thuật. Nó còn là:

contract
tài liệu
cơ sở review
cơ sở mock
cơ sở test
cơ chế quản trị thay đổi API

Với API công khai hoặc API nội bộ quy mô lớn, một công cụ chuẩn OpenAPI có đồng bộ Git giúp giữ contract nhất quán hơn.

Checklist chọn hướng tiếp cận

Dùng ưu tiên request nếu:

API đã tồn tại.
Bạn cần gọi và debug endpoint nhanh.
Bạn chủ yếu làm việc một mình hoặc trong nhóm nhỏ.
Collection request là đủ cho nhu cầu chia sẻ.
Rủi ro thay đổi contract thấp.

Dùng ưu tiên thiết kế nếu:

API chưa được triển khai.
Nhiều nhóm cần thống nhất trước.
Frontend cần làm song song với backend.
Bạn cần mock, docs hoặc review dựa trên contract.
API là sản phẩm công khai hoặc nền tảng nội bộ quan trọng.

Câu hỏi thường gặp

Bruno là ưu tiên request hay ưu tiên thiết kế?

Bruno là công cụ ưu tiên request. Mô hình cốt lõi của nó là tạo, tổ chức và gửi request được lưu dưới dạng file văn bản thuần túy. Nó phù hợp với việc khám phá và kiểm thử API đã tồn tại, không tập trung vào việc tạo OpenAPI contract trước khi API được xây dựng.

Tôi có thể làm việc ưu tiên thiết kế trong Bruno không?

Không tự nhiên theo cách của một công cụ tập trung vào spec. Bruno tập trung vào request, không phải trình thiết kế trực quan hoặc OpenAPI spec làm nguồn đáng tin cậy. Nếu bạn cần định nghĩa và review contract trước khi viết code, công cụ ưu tiên thiết kế dựa trên OpenAPI phù hợp hơn.

Tôi có phải từ bỏ Git để chuyển sang ưu tiên thiết kế không?

Không. Workflow Git-native cũng có thể áp dụng cho chính OpenAPI spec: file nằm trong repo, diff có thể review, thay đổi đi qua pull request. Chế độ Spec-First của Apidog giữ tài liệu OpenAPI trong repo với đồng bộ hai chiều, vì vậy ưu tiên thiết kế không có nghĩa là bỏ qua Git.

DEV Community