Bài 90: REST API cơ bản — cách network device "nói chuyện" qua API

💡 Liên hệ thực tế

Ở Bài 89, Cisco DNA Center đóng vai trò "bộ não trung tâm", giao tiếp lên trên qua Northbound API và xuống dưới qua Southbound API. Nhưng Northbound API cụ thể là gì, và một ứng dụng "nói chuyện" với DNA Center bằng cách nào?

Hãy hình dung anh Nam đặt đồ ăn qua app giao hàng. Anh không cần biết bên trong nhà hàng nấu nướng ra sao — anh chỉ cần gửi đúng một yêu cầu chuẩn: "tôi muốn đặt món X, giao tới địa chỉ Y". App trả lời bằng một mã trạng thái rõ ràng: đơn được xác nhận, hết món, hay giao sai địa chỉ. REST API hoạt động theo đúng nguyên lý đó: một cách "đặt hàng" chuẩn hóa để phần mềm này yêu cầu phần mềm khác (ví dụ DNA Center) thực hiện một hành động, và nhận lại phản hồi rõ ràng về kết quả.

📘 Kiến thức cốt lõi

1. API và REST API là gì

API (Application Programming Interface) là giao diện lập trình cho phép hai phần mềm giao tiếp với nhau — thay vì con người bấm chuột trên giao diện đồ họa, một chương trình có thể gửi yêu cầu trực tiếp và nhận lại dữ liệu có cấu trúc.

REST (Representational State Transfer) là một kiểu kiến trúc thiết kế API chạy trên nền giao thức HTTP quen thuộc — cùng giao thức mà trình duyệt web vẫn dùng hằng ngày. Một API tuân theo kiểu kiến trúc này được gọi là RESTful API hoặc REST API.

🎯 Đặc điểm cốt lõi của REST: stateless (không trạng thái) — mỗi request gửi lên server phải chứa đầy đủ thông tin cần thiết, server không cần nhớ lại request trước đó của cùng client. Điều này giúp REST API dễ mở rộng và dễ dự đoán hành vi.

2. CRUD và các HTTP method

Phần lớn thao tác với dữ liệu, dù trong ứng dụng nào, đều quy về 4 hành động cơ bản gọi tắt là CRUD: Create (tạo), Read (đọc), Update (cập nhật), Delete (xóa). REST API ánh xạ 4 hành động này vào các HTTP method (còn gọi là HTTP verb):

📎 Phân biệt PUT và POST: gọi PUT nhiều lần với cùng dữ liệu sẽ luôn cho ra cùng kết quả (tính chất idempotent — giống khái niệm đã học ở Bài 87 với Ansible); trong khi gọi POST nhiều lần có thể tạo ra nhiều tài nguyên trùng lặp mỗi lần gọi.

3. Mã trạng thái HTTP (HTTP Status Code)

Sau mỗi request, server luôn trả về một mã trạng thái 3 chữ số cho biết kết quả xử lý. Các nhóm mã phổ biến:

⚠️ Khi automation script gọi REST API, luôn phải kiểm tra mã trạng thái trả về trước khi tin tưởng nội dung phản hồi — một request có thể trả về nội dung JSON hợp lệ nhưng mã trạng thái lại báo lỗi (ví dụ do dữ liệu cache), nên bỏ qua bước kiểm tra mã trạng thái là một lỗi phổ biến khi viết script automation.

4. Cấu trúc của một REST API request

Một request REST API thường gồm các thành phần:

• URI (Uniform Resource Identifier): địa chỉ xác định chính xác tài nguyên cần thao tác, ví dụ https://dnac.example.com/dna/intent/api/v1/network-device.
• HTTP method: GET/POST/PUT/PATCH/DELETE như đã nêu ở mục 2.
• Header: thông tin bổ sung đi kèm request, ví dụ token xác thực, định dạng dữ liệu gửi kèm.
• Body (nếu có): dữ liệu gửi kèm request, với REST API hiện đại thường ở định dạng JSON — Bài 91 sẽ đi sâu vào cú pháp JSON và YAML.

📎 Về xác thực (authentication): thay vì gửi lại username/password ở mọi request, REST API hiện đại thường dùng token — một chuỗi định danh được cấp sau khi đăng nhập lần đầu, có thể giới hạn phạm vi và thời hạn sử dụng, giúp giảm rủi ro nếu 1 request bị lộ giữa đường truyền.

5. Ví dụ minh họa: gọi REST API lấy danh sách thiết bị từ DNA Center

Giả sử một ứng dụng cần lấy danh sách thiết bị mà DNA Center đang quản lý, request có thể mô tả như sau:

GET https://dnac.example.com/dna/intent/api/v1/network-device
Header: X-Auth-Token: <token đã được cấp sau khi đăng nhập>

Giải thích từng thành phần:

Nếu thành công, DNA Center phản hồi với mã trạng thái 200 OK cùng dữ liệu JSON chứa danh sách thiết bị. Nếu token hết hạn hoặc sai, DNA Center sẽ phản hồi 401 Unauthorized — script automation cần kiểm tra đúng mã này để biết cần đăng nhập lại lấy token mới, thay vì cố xử lý một dữ liệu phản hồi không hợp lệ.

💬 Hỏi & Đáp nhanh

❓ REST API có phải là một giao thức riêng, giống như NETCONF hay RESTCONF không?

✅ Không hẳn — REST là một kiểu kiến trúc thiết kế API, chạy trên nền giao thức HTTP đã có sẵn từ trước. RESTCONF (đã học ở Bài 87) chính là một ứng dụng cụ thể của REST API, chuyên dùng để cấu hình thiết bị mạng dựa trên mô hình dữ liệu YANG.

❓ Vì sao PUT được coi là idempotent còn POST thì không?

✅ Vì PUT thay thế toàn bộ tài nguyên bằng đúng dữ liệu được gửi lên — gọi lại nhiều lần với cùng dữ liệu vẫn cho cùng kết quả cuối cùng. POST tạo mới tài nguyên mỗi lần được gọi, nên gọi POST nhiều lần với cùng dữ liệu có thể tạo ra nhiều bản ghi trùng lặp.

❓ Nếu response trả về mã 404, script automation nên hiểu là gì?

✅ Mã 404 (Not Found) thuộc nhóm 4xx — lỗi phía client, cụ thể là tài nguyên được yêu cầu (theo đúng URI đã gửi) không tồn tại trên server, ví dụ gọi sai đường dẫn hoặc thiết bị không có trong danh sách quản lý của controller.

📝 Bài tập đánh giá

Câu 1: HTTP method nào phù hợp nhất để chỉ cập nhật riêng mô tả (description) của 1 interface, giữ nguyên toàn bộ cấu hình còn lại?

• A. GET
• B. POST
• C. PUT
• D. PATCH

Câu 2: Mã trạng thái HTTP nào cho biết request bị từ chối vì thông tin xác thực (token) không hợp lệ?

• A. 200 OK
• B. 401 Unauthorized
• C. 404 Not Found
• D. 500 Internal Server Error

👉 Đáp án:

Câu 1: D — PATCH dùng để cập nhật một phần dữ liệu của tài nguyên (ví dụ chỉ đổi description), trong khi PUT sẽ thay thế toàn bộ tài nguyên bằng dữ liệu mới gửi lên — nếu dùng PUT mà chỉ gửi mỗi description, các trường khác của interface có thể bị ghi đè mất.

Câu 2: B — 401 Unauthorized thuộc nhóm 4xx, báo hiệu request chưa được xác thực hợp lệ (ví dụ token sai hoặc hết hạn); 404 là không tìm thấy tài nguyên, còn 500 là lỗi phát sinh từ phía server.

📚 Bài viết thuộc khóa học CCNA của VNExperts

🧭 Điều hướng