Lesson 8.3: Postman & SDK Generation

Thời lượng: 20 phút
Level: Beginner
Yêu cầu: Đã nắm vững chuẩn OpenAPI.

Mục tiêu bài học

Sau bài học này, bạn sẽ:

• Biết cách xuất (Export) dữ liệu OpenAPI sang Postman Collection.
• Hiểu khái niệm Client SDK và tại sao nó quan trọng đối với một Design System.
• Sử dụng các bộ công cụ tự động tạo (Generators) thư viện gọi API.

Nội dung chính

1. Postman: Người bạn thân thiết của Developer

Mặc dù Swagger rất tốt, nhiều lập trình viên vẫn thích dùng Postman vì nó mạnh mẽ hơn trong việc tổ chức các kịch bản test (Test flows) và quản lý môi trường (Environment variables).

Quy trình chuẩn:

• Đừng bắt đồng nghiệp tự tạo từng request trong Postman.
• Hãy cung cấp một nút "Run in Postman" hoặc một file JSON Collection đã được cấu hình sẵn các biến ({{base_url}}, {{auth_token}}).

2. Client SDK là gì?

SDK (Software Development Kit) là một bộ thư viện code được viết bằng ngôn ngữ của Client (JavaScript, Swift, Java...).

Thay vì Frontend phải viết:

fetch('https://api.com/v1/users/1', { headers: { ... } })

Họ chỉ cần dùng SDK của bạn:

import { MyApiClient } from '@mycompany/api-sdk';
const user = await MyApiClient.users.get('1');

Lợi ích:

• Type-safety: Có gợi ý code (Intellisense) cực mạnh.
• Tự động xử lý: SDK tự bọc dữ liệu trong Envelope, tự gắn Trace ID, tự retry khi lỗi mạng.

3. Tự động hóa quá trình tạo SDK

Bạn không cần phải ngồi viết tay thư viện cho 5 ngôn ngữ khác nhau.

Công cụ: OpenAPI Generator Nó có thể đọc file openapi.yaml của bạn và tự động sinh ra hàng nghìn dòng code thư viện cho:

• TypeScript (Axios/Fetch)
• Java (Retrofit2/Spring)
• Swift (Alamofire)
• Go, Python...

Nguyên tắc then chốt

"Reduce Friction to Adoption."

Rào cản lớn nhất để một developer sử dụng API của bạn là công việc code "chân tay" (Boilerplate). Cung cấp Postman Collection và SDK giúp giảm 80% thời gian tích hợp, giúp họ yêu thích hệ thống của bạn hơn.

Thực hành

Bài tập 1: Export OpenAPI sang Postman

Yêu cầu:

• Nếu bạn đang có một file swagger.json, hãy tìm cách Import nó vào Postman.
• Quan sát cách Postman biến các "Path Variables" thành các biến trong URL.

Tình huống thực tế

Scenario 1: API thay đổi tên trường

Bối cảnh: Bạn đổi tên trường user_name thành username trong API.

Vấn đề: Hàng chục service Frontend sẽ bị lỗi vì họ đang gõ tay tên trường đó.

Giải quyết: Nếu bạn cung cấp SDK (TypeScript), ngay khi bạn cập nhật file OpenAPI và generate lại SDK mới:

1. Dự án Frontend của đồng nghiệp sẽ báo lỗi đỏ (Compile error) ngay lập tức vì trường user_name không còn tồn tại.
2. IDE sẽ gợi ý: "Bạn có muốn đổi sang username không?". Điều này giúp hệ thống trở nên cực kỳ bền vững (Robust).

Câu hỏi phỏng vấn

Junior/Mid Level

1. Q: Tại sao ta nên dùng biến môi trường (Environment) trong Postman thay vì gõ cứng URL? A: Để có thể chuyển đổi nhanh giữa các môi trường (Local, Staging, Production) mà không phải thay đổi nội dung request. Chỉ cần chọn tên môi trường ở góc phải màn hình, toàn bộ URL và Token sẽ tự động thay đổi theo.

Tóm tắt

Những điều cần nhớ

• Postman Collection giúp test API nhanh và chuyên nghiệp.
• SDK giúp Frontend code nhàn hơn, an toàn hơn (Type-safe).
• Sử dụng OpenAPI Generator để tự động hóa, tránh sai sót do con người.

Bước tiếp theo

🎉 Chúc mừng! Bạn đã hoàn thành Module 8: API Documentation.

Giờ đây, Backend của bạn không còn là một "hộp đen" bí ẩn nữa. Nó đã được phơi bày một cách khoa học qua:

• Tiêu chuẩn OpenAPI.
• Môi trường Sandbox tương tác.
• Bộ sưu tập Postman và SDK tiện lợi.

Module cuối cùng: Module 9: Observability & Monitoring - Học cách theo dõi sức khỏe hệ thống và "ngửi" thấy lỗi trước khi người dùng phàn nàn.

Bắt đầu Module 9 →