Giải thích API bằng ví dụ nhà hàng

API là contract để yêu cầu hệ thống khác làm việc hoặc trả dữ liệu. Trong ví dụ nhà hàng, menu định nghĩa request hợp lệ, phục vụ bàn chuyển request và bếp xử lý implementation ẩn phía sau.

Nhìn nhanh

Câu hỏi	Câu trả lời thực tế
Dùng khi nào?	Weather client gửi tên thành phố và nhận dữ liệu nhiệt độ có cấu trúc mà không cần biết sensor, forecast và database vận hành thế nào bên trong API.
Cần làm gì?	Dùng browser hoặc API client gọi một endpoint public chỉ đọc; ghi URL, method, status code, header và JSON body.
Biết là đúng bằng cách nào?	Request hợp lệ trả status và shape đã mô tả; parameter sai tạo client error có kiểm soát thay vì crash khó hiểu.
Lỗi hay gặp?	Ví dụ nhà hàng chỉ giải thích contract boundary; API thật còn cần authentication, quota, versioning, retry và observability.

flowchart LR
  A[Câu hỏi] --> B[Giải thích API bằng ví dụ nhà hàng]
  B --> C[Ví dụ nhỏ]
  C --> D[Bằng chứng]

Điểm quan trọng của sơ đồ là không dừng ở định nghĩa: hãy nối khái niệm với một ví dụ nhỏ và bằng chứng có thể quan sát.

Ví dụ đã phân tích

Weather client gửi tên thành phố và nhận dữ liệu nhiệt độ có cấu trúc mà không cần biết sensor, forecast và database vận hành thế nào bên trong API.

Trước khi làm, hãy viết dấu hiệu thành công. Sau đó chỉ thay đổi một yếu tố, quan sát kết quả và ghi lại assumption. Với Giải thích API bằng ví dụ nhà hàng, cách này giúp tách điều bạn biết khỏi điều bạn chỉ đang đoán.

Thực hành trong 20–30 phút

Mục tiêu: Dùng browser hoặc API client gọi một endpoint public chỉ đọc; ghi URL, method, status code, header và JSON body.

1. Ghi lại trạng thái ban đầu và điều bạn dự đoán.
2. Thực hiện phiên bản nhỏ nhất, không thêm công cụ chưa cần thiết.
3. Thay đổi đúng một input hoặc constraint rồi chạy lại.
4. Lưu command, screenshot, output hoặc checklist làm bằng chứng.

Kết quả mong đợi: Request hợp lệ trả status và shape đã mô tả; parameter sai tạo client error có kiểm soát thay vì crash khó hiểu.

Sai ở đâu và sửa thế nào

Ví dụ nhà hàng chỉ giải thích contract boundary; API thật còn cần authentication, quota, versioning, retry và observability.

Khi kết quả khác dự đoán, đừng đổi nhiều thứ cùng lúc. Kiểm tra input, version, environment, quyền truy cập và log trước; sau đó lặp lại từ ví dụ nhỏ nhất.

Định nghĩa hoàn thành

• Tôi giải thích được khái niệm bằng ngôn ngữ của mình.
• Tôi đã hoàn thành ví dụ nhỏ và giữ bằng chứng.
• Tôi biết một failure mode và cách kiểm tra nó.
• Người khác có thể làm lại mà không phải đoán bước còn thiếu.

Đi sâu hơn

Mở resource hoặc repository đi kèm ở cuối trang khi bạn cần implementation đầy đủ. Hãy kiểm tra version hiện hành trước khi dùng command trong dự án thật.