Để phía giao diện và phía dịch vụ giao tiếp được với nhau, hai bên cần có một thống nhất về chuẩn giao tiếp. Trong hệ thống CEMS, việc tương tác này được thực hiện thông qua REST API sử dụng giao thức HTTP và định dạng chuẩn dữ liệu là JSON.
Ở mô hình giao tiếp này, phía máy khách sẽ gửi một một yêu cầu tới máy chủ (http request), máy chủ xử lý yêu cầu và gửi trả lại một phản hồi (http response). Để cài đặt các thao tác nghiệp vụ, các API được quy định sử dụng một quy ước về cách dùng giao thức HTTP như sau:
Quy ước cho Http Request
• Dùng HTTP Post khi muốn tạo mới một tài nguyên.
• Dùng HTTP Put khi muốn cập nhật dữ liệu cho một tài nguyên.
• Dùng HTTP Get khi muốn thực hiện một truy vấn để lấy thông tin về tài nguyên.
• Dùng HTTP Delete khi muốn xóa một tài nguyên.
Quy ước cho Http Response
Mỗi một Http Response bao gồm hai thành phần quan trọng là mã trạng thái (http code) và nội dung (body). Mã trạng thái thể hiện trạng thái kết quả thực hiện sau khi phía máy chủ xử lý một Http Request, còn phần nội dung là thành phần chứa kết quả trả về cho phía người dùng. Thông thường, một số mã trạng thái phổ biến được sử dụng như mô tả trong bảng 3.2 [30].
58
Bảng 3.2. Một số mã HTTP thông dụng
Mã Http Nội dung Ý nghĩa
200 OK một yêu cầu được thực hiện thành công
201 Created một yêu cầu tạo mới một tài nguyên thành công 204 No Content một yêu cầu được thực hiện thành công, nhưng
không có nội dung trả về
400 Bad Request phía máy chủ không xử lý được yêu cầu 403 Forbidden yêu cầu không được phép chấp nhận 404 Not Found tài nguyên được yêu cầu không tìm thấy
406 Not Acceptable nội dung trao đổi giữa máy chủ với máy khách không đúng chuẩn (gửi sai định dạng dữ liệu…) 500 Internal Server Error Các mã thuộc nhóm 5xx liên quan tới những lỗi
thuộc về phía máy chủ
Để làm rõ cơ chế hoạt động của API, chúng ta xem xét một ví dụ sau: để lấy thông tin của một khách hàng theo mã khách hàng “C001”, phía máy khách sẽ gửi một yêu cầu theo phương thức Get đến tầng dịch vụ, máy chủ xử lý và gửi trả lại một phản hồi với mã trạng thái là 200 cùng với các dữ liệu liên quan.
Hình 3.16. Lấy thông tin khách hàng theo mã khách hàng
Nội dung dữ liệu trả về dưới dạng JSON được thể hiện chi tiết trong hình 3.17. Việc thực hiện các theo tác khác như Post/Put/Delete cũng được diễn ra theo cách tương tự.
59
Trong quá trình xây dựng các API, việc tuân thủ các chuẩn và tạo ra các đặc tả cho các API đóng vai trò quan trọng, vì thông qua các đặc tả này mà phía người sử dụng API sẽ hiểu rõ được cách dùng của các thành phần, từ đó tránh được những lỗi không mong muốn khi tích hợp tầng giao diện với tầng dịch vụ. Dự án CEMS sử dụng Swagger49, một công cụ sinh ra các tài liệu đặc tả cho các API.
Ví dụ đặc tả chi tiết cho API: GET /customers/{customerCode} được mô tả trong hình 3.18.
Hình 3.18. Ví dụ đặc tả chi tiết cho API: GET /customers/{customerCode}