Nền tảng API quy trình thiết kế API trước

Tóm tắt

Cách tiếp cận thiết kế trước (design-first) nghĩa là bạn viết đặc tả API trước khi triển khai mã. Đặc tả này trở thành nguồn chân lý cho mock, tài liệu, kiểm thử và client/server stubs. Nếu chọn đúng nền tảng, bạn có thể giảm đáng kể việc tài liệu và mã bị lệch nhau. Bài viết này hướng dẫn cách áp dụng workflow design-first và đánh giá các công cụ phù hợp, trong đó Apidog là một nền tảng thiết kế trước hoàn chỉnh.

Dùng thử Apidog hôm nay

Apidog Dùng thử Apidog miễn phí

Giới thiệu

Nhiều đội phát triển API theo cách code-first:

1. Viết route.
2. Thêm annotation/decorator.
3. Chạy tool sinh tài liệu.
4. Chia sẻ tài liệu cho frontend hoặc bên tích hợp.

Cách này hoạt động tốt ở giai đoạn đầu, nhưng dễ phát sinh vấn đề khi API thay đổi liên tục.

Ví dụ:

// Tài liệu ghi:
["active", "inactive"]

// API thực tế trả về:
[
  { "value": "active" },
  { "value": "inactive" }
]

Lỗi kiểu này thường xảy ra khi mã được cập nhật nhưng annotation hoặc tài liệu không được cập nhật theo.

Design-first đảo ngược quy trình đó:

1. Định nghĩa hợp đồng API bằng OpenAPI.
2. Sinh mock từ đặc tả.
3. Frontend tích hợp với mock.
4. Backend triển khai theo đặc tả.
5. Kiểm thử xác thực implementation có khớp contract hay không.

Điểm quan trọng: đặc tả không phải tài liệu phụ trợ. Nó là nguồn chân lý duy nhất.

Thiết kế trước có nghĩa là gì trong thực tế

Design-first là một workflow, không phải một công nghệ cụ thể. Với REST API, workflow thường xoay quanh OpenAPI.

1. Trước khi viết mã

Bạn định nghĩa API dưới dạng đặc tả OpenAPI, bao gồm:

• Endpoint path và HTTP method
• Path/query/header parameters
• Request body schema
• Response schema cho các mã trạng thái như 200, 400, 401, 422, 500
• Authentication requirements
• Field descriptions
• Example payloads

Ví dụ một endpoint đơn giản:

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: "Thành công"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserProfile"
        "404":
          description: "Không tìm thấy người dùng"

Đây là thời điểm nên thống nhất các quyết định quan trọng:

• Tên endpoint
• Cấu trúc dữ liệu
• Cách phân trang
• Format lỗi
• Quy ước đặt tên field
• Authentication flow

2. Trong quá trình phát triển

Sau khi đặc tả được lưu, bạn publish mock server.

Frontend có thể gọi mock ngay:

const res = await fetch("https://mock.example.com/users/123");
const user = await res.json();

console.log(user.name);

Backend triển khai theo đặc tả:

app.get("/users/:id", async (req, res) => {
  const user = await userService.findById(req.params.id);

  if (!user) {
    return res.status(404).json({
      code: "USER_NOT_FOUND",
      message: "Không tìm thấy người dùng"
    });
  }

  return res.json(user);
});

Hai nhóm làm việc song song mà không cần chờ nhau.

3. Sau khi triển khai

Bạn chạy kiểm thử để xác thực API thực tế có khớp đặc tả không.

Các kiểm tra nên bao gồm:

• Status code
• Required fields
• Data type
• Enum values
• Nested object structure
• Error response format

Nếu implementation trả về sai contract, test phải fail.

4. Khi yêu cầu thay đổi

Quy trình nên là:

1. Cập nhật đặc tả.
2. Review thay đổi với frontend/backend.
3. Cập nhật mock.
4. Cập nhật implementation.
5. Chạy lại contract/schema tests.

Không nên âm thầm sửa implementation trước rồi cập nhật tài liệu sau.

Những gì một nền tảng thiết kế trước cần có

Không phải mọi công cụ API đều phù hợp với workflow design-first. Một nền tảng tốt cần hỗ trợ các phần sau.

Trình chỉnh sửa API trực quan

Viết YAML thủ công dễ lỗi, đặc biệt với schema lớn hoặc nested object.

Một editor tốt nên hỗ trợ:

• Tạo endpoint bằng form
• Định nghĩa request/response schema
• Tái sử dụng schema qua components
• Validate OpenAPI ngay khi chỉnh sửa
• Cho phép xem/chỉnh YAML hoặc JSON khi cần

Ví dụ schema dùng lại:

components:
  schemas:
    UserProfile:
      type: object
      required:
        - id
        - email
      properties:
        id:
          type: string
          example: "usr_123"
        email:
          type: string
          format: email
          example: "dev@example.com"
        displayName:
          type: string
          example: "Nguyen Van A"

Xác thực OpenAPI

Đặc tả phải hợp lệ trước khi được dùng để sinh mock, tài liệu hoặc code.

Tool nên bắt lỗi như:

• Thiếu required
• Sai $ref
• Response không có description
• Schema không hợp lệ
• Enum không khớp kiểu dữ liệu

Việc phát hiện lỗi trong lúc thiết kế rẻ hơn nhiều so với phát hiện khi tích hợp.

Tạo mock tự động từ đặc tả

Workflow lý tưởng:

1. Định nghĩa endpoint.
2. Lưu đặc tả.
3. Nhận mock URL.
4. Frontend bắt đầu tích hợp.

Mock nên sinh dữ liệu dựa trên schema:

email:
  type: string
  format: email

age:
  type: integer
  minimum: 18
  maximum: 99

status:
  type: string
  enum: [active, inactive, blocked]

Mock response nên trả về dữ liệu hợp lệ với các constraint đó.

Xem trước tài liệu với ví dụ thực tế

Trong design-first, tài liệu được review trước khi triển khai.

Tài liệu nên hiển thị rõ:

• Endpoint summary
• Request parameters
• Request body
• Response schema
• Example response
• Error cases
• Authentication requirements

Nếu người đọc không hiểu field trong tài liệu, rất có thể implementation cũng sẽ gây nhầm lẫn.

Quy trình đánh giá nhóm

API contract nên được review giống như code.

Một workflow thực tế:

1. Developer tạo hoặc sửa endpoint.
2. Thêm comment vào field hoặc response cần thảo luận.
3. Frontend/backend/product review.
4. Resolve comment.
5. Chốt đặc tả cho sprint hoặc feature.

Nền tảng nên hỗ trợ comment, lịch sử thay đổi và theo dõi ai đã sửa gì.

Xuất sang OpenAPI tiêu chuẩn

Đặc tả không nên bị khóa trong một công cụ.

Bạn cần có thể export OpenAPI 3.x để dùng với:

• Code generator
• API gateway
• Test framework
• Documentation portal
• CI pipeline

Ví dụ dùng openapi-generator sau khi export:

openapi-generator-cli generate \
  -i openapi.yaml \
  -g typescript-fetch \
  -o ./generated/client

Apidog như một nền tảng thiết kế trước

Apidog được xây dựng quanh đặc tả API. Tab thiết kế, mock server, tài liệu và kiểm thử cùng dùng một định nghĩa API cơ bản.

Trình chỉnh sửa OpenAPI trực quan

Trong Apidog, mỗi endpoint được định nghĩa bằng giao diện có cấu trúc:

• Path
• Method
• Parameters
• Request body
• Response body
• Status code
• Schema
• Example
• Validation rules

Bạn không bắt buộc phải viết YAML thủ công. Tuy nhiên, nếu cần, Apidog vẫn cung cấp chế độ xem YAML/JSON để chỉnh trực tiếp.

Cách triển khai thực tế:

1. Tạo project.
2. Mở tab thiết kế API.
3. Thêm endpoint mới, ví dụ GET /users/{id}.
4. Thêm path parameter id.
5. Định nghĩa response 200.
6. Tạo hoặc tham chiếu schema UserProfile.
7. Thêm response lỗi như 404.

Các schema dùng chung nên được đặt trong components.

Ví dụ:

components:
  schemas:
    ErrorResponse:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
          example: "USER_NOT_FOUND"
        message:
          type: string
          example: "Không tìm thấy người dùng"

Sau đó tham chiếu schema này ở nhiều endpoint:

responses:
  "404":
    description: Không tìm thấy tài nguyên
    content:
      application/json:
        schema:
          $ref: "#/components/schemas/ErrorResponse"

Xem trước tài liệu theo thời gian thực

Khi bạn chỉnh endpoint, tài liệu được cập nhật theo thời gian thực.

Điều này hữu ích trong giai đoạn review:

• Product manager kiểm tra mô tả nghiệp vụ.
• Frontend kiểm tra response có đủ dữ liệu không.
• Backend kiểm tra format lỗi và constraint.
• QA kiểm tra status code và edge cases.

Bạn có thể chia sẻ link tài liệu để người khác review mà không cần cài đặt thêm.

Smart Mock: từ đặc tả đến mock hoạt động

Khi lưu endpoint trong Apidog, mock server có thể được dùng ngay. Mock response được tạo dựa trên schema.

Ví dụ schema:

type: object
properties:
  id:
    type: string
    example: "usr_123"
  email:
    type: string
    format: email
  status:
    type: string
    enum:
      - active
      - inactive

Mock có thể trả về payload tương ứng:

{
  "id": "usr_123",
  "email": "user@example.com",
  "status": "active"
}

Apidog cũng hỗ trợ rule mock cho các kịch bản cụ thể, ví dụ:

• Trả về 404 khi path parameter là 0
• Trả về payload cụ thể khi query parameter có giá trị nhất định
• Mô phỏng response lỗi để frontend xử lý edge case

Ví dụ frontend có thể bắt đầu với mock:

async function getUser(id: string) {
  const res = await fetch(`${MOCK_BASE_URL}/users/${id}`);

  if (!res.ok) {
    throw new Error("Không thể tải người dùng");
  }

  return res.json();
}

Đánh giá nhóm và theo dõi thay đổi

Trong Apidog, thay đổi đặc tả API hiển thị cho các thành viên trong workspace. Nhóm có thể comment vào endpoint hoặc field cụ thể và xem lịch sử thay đổi.

Với workflow design-first, bạn có thể áp dụng quy trình:

1. Tạo endpoint nháp.
2. Gắn comment cho các phần cần xác nhận.
3. Review với frontend/backend.
4. Chỉnh schema hoặc response.
5. Chốt contract.
6. Bắt đầu implementation.

Cách này giúp thay đổi API không bị thực hiện âm thầm trong code.

Thiết kế trước so với mã trước: các đánh đổi thực tế

Design-first không phải lúc nào cũng là lựa chọn tốt nhất. Dưới đây là so sánh thực tế.

Ưu điểm của design-first

• Frontend và backend có thể làm việc song song.
• Mock có sẵn từ đầu.
• Tài liệu chính xác hơn vì được sinh từ contract.
• Vấn đề tích hợp được phát hiện sớm.
• API contract rõ ràng và có thể kiểm chứng.
• Thay đổi API được review trước khi triển khai.

Nhược điểm của design-first

• Cần thời gian ban đầu để viết đặc tả.
• Nhóm phải học OpenAPI hoặc công cụ đặc tả.
• Cần kỷ luật để giữ implementation khớp contract.
• Nếu đặc tả quá chi tiết quá sớm, nhóm có thể bị khóa vào quyết định chưa chắc đúng.

Ưu điểm của code-first

• Nhanh hơn cho prototype hoặc dự án nhỏ.
• Ít quy trình hơn với developer độc lập.
• Không cần học công cụ thiết kế API ngay từ đầu.

Nhược điểm của code-first

• Tài liệu dễ bị lệch với implementation.
• Frontend thường phải chờ backend.
• Contract ngầm định nên khó phát hiện breaking change.
• Refactor API thường kéo theo cập nhật tài liệu thủ công.

Với nhóm có nhiều hơn một kỹ sư cùng làm trên API, design-first thường đáng đầu tư hơn, đặc biệt khi frontend và backend cần phối hợp chặt.

Các công cụ hỗ trợ workflow thiết kế trước

Apidog

Apidog cung cấp workflow design-first trong một công cụ:

• Trình chỉnh sửa API trực quan
• Mock server
• Tài liệu API
• Kiểm thử
• Review nhóm
• Theo dõi thay đổi

Điểm mạnh là mock được kết nối trực tiếp với đặc tả, giúp frontend bắt đầu tích hợp sớm.

Stoplight Studio

Stoplight Studio là trình chỉnh sửa OpenAPI mạnh, có Spectral linting để enforce style và rule cho đặc tả.

Phù hợp với tổ chức cần quản trị API contract nghiêm ngặt. Tuy nhiên, mock server và test runner không phải trọng tâm chính như các nền tảng tích hợp đầy đủ.

SwaggerHub

SwaggerHub là nền tảng OpenAPI lâu đời, phổ biến trong môi trường doanh nghiệp.

Phù hợp với tổ chức đã dùng hệ sinh thái Swagger và cần quản lý đặc tả tập trung. Khả năng mock và testing không phải điểm mạnh chính.

Postman với API Builder

Postman có API Builder để tạo đặc tả OpenAPI.

Tuy nhiên, workflow giữa API design và collection có thể không liền mạch. Mock server thường cần cấu hình qua collection thay vì tự động sinh trực tiếp từ đặc tả.

Phù hợp với nhóm code-first đã dùng Postman và muốn bổ sung một phần tài liệu/thiết kế.

Insomnia với chế độ tài liệu

Insomnia hỗ trợ chỉnh sửa OpenAPI và mock cơ bản.

Phù hợp với developer độc lập hoặc nhóm nhỏ cần công cụ nhẹ. Với workflow design-first phức tạp, các nền tảng chuyên dụng sẽ phù hợp hơn.

Thiết lập workflow design-first trong Apidog

Dưới đây là một quy trình thực tế có thể áp dụng cho một feature mới.

Bước 1: Bắt đầu bằng đặc tả, không phải request collection

Tạo project mới trong Apidog và mở phần thiết kế API.

Trước khi gửi request đầu tiên, hãy định nghĩa tối thiểu:

• Endpoint path
• HTTP method
• Request parameters
• Response 200
• Response lỗi phổ biến

Ví dụ feature: lấy danh sách đơn hàng.

GET /orders?page=1&pageSize=20

Response schema nên được định nghĩa trước:

{
  "items": [
    {
      "id": "ord_123",
      "status": "paid",
      "total": 120000
    }
  ],
  "page": 1,
  "pageSize": 20,
  "total": 100
}

Bước 2: Định nghĩa schema dùng chung trước

Trước khi thêm nhiều endpoint, hãy tạo các schema dùng lại:

• ErrorResponse
• PaginationMeta
• UserProfile
• Order
• Address

Ví dụ pagination wrapper:

PaginationMeta:
  type: object
  required:
    - page
    - pageSize
    - total
  properties:
    page:
      type: integer
      minimum: 1
    pageSize:
      type: integer
      minimum: 1
      maximum: 100
    total:
      type: integer
      minimum: 0

Việc này giúp tránh mỗi endpoint trả về một kiểu phân trang khác nhau.

Bước 3: Lấy mock URL sớm

Sau khi lưu endpoint, lấy mock URL trong Apidog và chia sẻ cho frontend.

Frontend có thể cấu hình base URL:

const API_BASE_URL = import.meta.env.VITE_API_BASE_URL;

export async function listOrders() {
  const res = await fetch(`${API_BASE_URL}/orders?page=1&pageSize=20`);
  return res.json();
}

Trong môi trường local:

VITE_API_BASE_URL=https://mock-api.example.com

Khi backend sẵn sàng, chỉ cần đổi base URL sang API thật.

Bước 4: Review tài liệu trước khi viết mã

Mở bản preview tài liệu và kiểm tra:

• Tên endpoint có rõ nghĩa không?
• Field nào là required?
• Enum có đầy đủ trạng thái không?
• Error response có thống nhất không?
• Có example cho request/response chưa?

Nếu tài liệu khó hiểu, hãy sửa đặc tả trước.

Bước 5: Khóa đặc tả cho phạm vi sprint

Sau khi review xong, coi contract là đã chốt cho feature hoặc sprint đó.

Nếu cần thay đổi, quy trình nên là:

1. Cập nhật đặc tả.
2. Thông báo người liên quan.
3. Review tác động.
4. Cập nhật mock.
5. Cập nhật implementation.
6. Chạy lại test.

Không nên để backend tự thay đổi response mà frontend không biết.

Bước 6: Chạy kiểm thử xác thực schema trong CI

Sau khi backend triển khai, thêm bước kiểm thử schema vào pipeline.

Ví dụ pipeline tổng quát:

name: API Contract Test

on:
  pull_request:
    branches:
      - main

jobs:
  contract-test:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Install dependencies
        run: npm ci

      - name: Run API tests
        run: npm run test:api

Mục tiêu là đảm bảo response thực tế vẫn khớp schema trong đặc tả.

Checklist áp dụng design-first cho một endpoint mới

Trước khi bắt đầu backend implementation, hãy kiểm tra:

• [ ] Endpoint path đã được định nghĩa.
• [ ] HTTP method đúng với hành vi API.
• [ ] Path/query/header parameters đã có type và description.
• [ ] Request body đã có schema nếu cần.
• [ ] Response 200 hoặc 201 đã có schema.
• [ ] Response lỗi phổ biến đã được định nghĩa.
• [ ] Schema dùng chung được tái sử dụng bằng $ref.
• [ ] Example request/response đã có.
• [ ] Mock URL hoạt động.
• [ ] Frontend đã xác nhận contract đủ dùng.
• [ ] Tài liệu preview dễ hiểu.
• [ ] Test schema được thêm vào workflow kiểm thử.

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

Design-first chỉ dành cho REST API?

Không. Nguyên tắc design-first áp dụng cho mọi giao thức có thể định nghĩa contract:

• REST với OpenAPI
• GraphQL schema-first
• gRPC với protobuf
• AsyncAPI cho hệ thống event-driven

Apidog hỗ trợ thiết kế REST và GraphQL. Với gRPC, file proto đóng vai trò contract trước.

Có cần định nghĩa toàn bộ API trước khi phát triển không?

Không.

Bạn có thể áp dụng design-first theo từng feature. Ví dụ sprint này chỉ làm module đơn hàng, bạn chỉ cần định nghĩa contract cho các endpoint liên quan đến đơn hàng.

Áp dụng từng phần vẫn có giá trị.

Design-first có phù hợp với agile sprint không?

Có.

Một cách triển khai thực tế:

1. Đầu sprint: thiết kế API contract cho feature.
2. Giữa sprint: frontend dùng mock, backend triển khai.
3. Cuối sprint: chạy contract/schema tests.
4. Review: cập nhật đặc tả nếu có thay đổi.

API design trở thành một phần của sprint planning thay vì bước tài liệu cuối cùng.

Nếu implementation cần khác đặc tả ban đầu thì sao?

Điều đó có thể xảy ra.

Quy trình đúng là:

1. Cập nhật đặc tả trước.
2. Review với các bên liên quan, đặc biệt là frontend.
3. Cập nhật mock.
4. Sửa implementation.
5. Chạy lại test.

Như vậy đặc tả vẫn là nguồn chân lý duy nhất.

Có thể tạo server stubs từ OpenAPI export của Apidog không?

Có.

Bạn có thể export đặc tả từ Apidog dưới dạng OpenAPI 3.x, sau đó dùng generator tiêu chuẩn.

Ví dụ:

openapi-generator-cli generate \
  -i openapi.yaml \
  -g nodejs-express-server \
  -o ./server-stub

openapi-generator hỗ trợ nhiều ngôn ngữ và framework server.

Xử lý versioning đặc tả như thế nào?

Apidog duy trì lịch sử thay đổi trong project.

Với thay đổi lớn cần duy trì song song, ví dụ v1 và v2, bạn có thể dùng project hoặc nhánh riêng biệt để quản lý từng phiên bản.

Kết luận

Design-first yêu cầu một chút kỷ luật ở giai đoạn đầu, nhưng đổi lại giúp giảm chi phí tích hợp, giảm sai lệch tài liệu và cho phép frontend/backend làm việc song song.

Workflow nên bắt đầu từ contract:

1. Viết đặc tả.
2. Sinh mock.
3. Review tài liệu.
4. Triển khai backend.
5. Xác thực implementation bằng test.

Nền tảng bạn chọn phải làm cho bước viết đặc tả đủ nhanh và dễ dùng. Nếu việc tạo contract quá chậm, nhóm sẽ quay lại code-first. Với trình chỉnh sửa trực quan, mock tức thì và tài liệu cập nhật theo đặc tả, Apidog giúp design-first trở thành workflow thực tế hơn cho đội phát triển API.