BA thời nay không thể 'mù' API: Cẩm nang đọc hiểu RESTful & JSON cơ bản

Bài viết này được trích xuất và biên tập lại từ bản gốc trên blog ITPrep - Cẩm nang IT & Cheatsheet.

Chào anh em cộng đồng Dev.to! Hôm nay mình xin chia sẻ một chủ đề mà có lẽ anh em Backend nào cũng từng "đau đầu": Giao tiếp hệ thống với các bạn Business Analyst (BA).

Thực tế, BA thời nay nếu chỉ biết vẽ luồng trên Figma mà "mù" API thì rất khó làm việc. Bài viết này là một cẩm nang nhỏ mình đúc kết lại, nhằm giúp các bạn BA (đặc biệt là Fresher hoặc BA tay ngang) nắm vững kiến trúc RESTful và JSON để làm việc mượt mà hơn với đội Dev, đưa ra các yêu cầu tích hợp chính xác hơn.

1. API là gì và Vì sao BA không thể "mù" API?

API (Application Programming Interface) là một tập hợp các quy tắc cho phép các ứng dụng phần mềm giao tiếp với nhau. Hãy hình dung API như một người phục vụ trong nhà hàng: bạn không cần biết nhà bếp hoạt động thế nào, chỉ cần nói món bạn muốn (gửi yêu cầu), và người phục vụ sẽ mang món ăn ra (trả về dữ liệu/kết quả).

Đối với BA, hiểu API là chìa khóa để:

• Phân tích yêu cầu tích hợp: Xác định các điểm chạm giữa các hệ thống, hiểu rõ luồng dữ liệu trao đổi.
• Giao tiếp với đội phát triển: Sử dụng ngôn ngữ chung, tránh "ông nói gà bà nói vịt" khi truyền đạt requirement.
• Kiểm thử và xác nhận: Hiểu cách dữ liệu được gửi/nhận để hỗ trợ kiểm thử tích hợp (Integration Test).

2. Giải mã RESTful API: Kiến trúc cốt lõi

REST (Representational State Transfer) là một kiểu kiến trúc phần mềm được sử dụng để thiết kế các hệ thống mạng. Một API tuân thủ các nguyên tắc của REST được gọi là RESTful API.

Các phương thức HTTP chính mà BA cần biết

RESTful API sử dụng các phương thức HTTP để thực hiện các thao tác CRUD (Create, Read, Update, Delete):

• GET: Yêu cầu lấy dữ liệu từ một tài nguyên cụ thể. (READ)
• POST: Gửi dữ liệu để tạo một tài nguyên mới. (CREATE)
• PUT: Cập nhật toàn bộ một tài nguyên đã tồn tại. (UPDATE)
• PATCH: Cập nhật một phần của tài nguyên.
• DELETE: Xóa một tài nguyên.

Hiểu về Resource và Endpoint

Trong REST, mọi thứ đều là tài nguyên (Resource). Mỗi tài nguyên được xác định bởi một URL duy nhất, gọi là Endpoint.

Ví dụ:

• /users: Tập hợp các tài nguyên người dùng.
• /products/456/reviews: Tập hợp các đánh giá cho sản phẩm có ID 456.

Ví dụ về một yêu cầu RESTful API để lấy thông tin người dùng:

GET /api/users/123 HTTP/1.1
Host: example.com
Accept: application/json

3. JSON: Ngôn ngữ dữ liệu "quốc dân"

JSON (JavaScript Object Notation) là một định dạng trao đổi dữ liệu nhẹ, dễ đọc và dễ viết. Đây là định dạng chuẩn cho hầu hết các RESTful API hiện đại.

Cấu trúc của JSON đi theo cặp Key - Value (Khóa - Giá trị), được xây dựng dựa trên Đối tượng ({}) và Mảng ([]).

Ví dụ một cấu trúc JSON mà hệ thống trả về:

{
  "id": "123",
  "name": "Nguyen Van A",
  "email": "nguyenvana@example.com",
  "isActive": true,
  "roles": ["admin", "editor"],
  "address": {
    "street": "123 Le Loi",
    "city": "Ho Chi Minh",
    "zipCode": "70000"
  },
  "lastLogin": null
}

Nhìn vào đây, BA sẽ biết hệ thống trả về ID, tên, trạng thái hoạt động... Từ đó, bạn có thể thiết kế Wireframe hiển thị chính xác các trường dữ liệu này mà không cần hỏi lại Dev.

4. Cẩm nang thực hành cho BA: Đọc hiểu tài liệu API (Swagger/OpenAPI)

Hầu hết các API hiện đại đều có tài liệu được tạo tự động (như Swagger). Khi đọc tài liệu này, BA cần soi kỹ 3 yếu tố:

1. Endpoint & HTTP Method: Chức năng này gọi vào đường dẫn nào? Dùng GET hay POST?
2. Phân tích Request (Dữ liệu gửi lên):
   • Path Parameters: Ví dụ {id} trong /users/{id}
   • Query Parameters: Ví dụ /users?status=active
   • Request Body: Dữ liệu JSON gửi kèm (tham số nào bắt buộc, tham số nào tùy chọn, kiểu dữ liệu là String hay Integer?).
3. Phân tích Response (Dữ liệu trả về):
   • Status Codes: Hiểu mã 200 OK (Thành công), 400 Bad Request (Lỗi dữ liệu gửi lên), 500 Internal Server Error (Lỗi server).
   • Response Body: Cấu trúc JSON nhận được là gì?

5. Ma trận quyết định: BA cần hiểu API đến mức độ nào?

Không phải BA nào cũng cần code được API. Dưới đây là ma trận giúp bạn xác định mức độ cần thiết:

Kết luận

Đối với một Business Analyst, việc trang bị kiến thức về kiến trúc RESTful và định dạng dữ liệu JSON không chỉ xóa bỏ rào cản kỹ thuật mà còn nâng cao vị thế của bạn trong dự án. Hiểu API, bạn không chỉ là người "truyền tin" mà đã thực sự trở thành người thiết kế giải pháp hệ thống.

Hy vọng bài viết này hữu ích với anh em. Nếu thấy hay, mọi người có thể tham khảo thêm các tài nguyên phỏng vấn và kỹ năng thực chiến dành cho dân IT tại ITPrep - Blog chia Cẩm nang IT & Cheatsheet.

Bài viết đề xuất thêm: Công thức viết User Story 'thuyết phục mọi Dev' chuẩn INVEST