Chuẩn hoá dữ liệu request và response trong REST API

Có 2 thứ mà khi nhắc đến REST API chúng ta không thể bỏ qua được, đó là request và response. Giống như việc khi bạn nhìn thấy một API ở đâu đó, thứ mà trong đầu bạn nghĩ ra đầu tiên đó là với API đó thì request của nó là gì, response là gì.

Là một backend developer, công việc hàng ngày của bạn bao gồm việc thiết kế API, lập trình API và trả dữ liệu từ API cho các dịch vụ gọi vào. Việc chuẩn hoá dữ liệu request và response sẽ giúp cho công việc hàng ngày của bạn dễ dàng hơn cũng như có thể tái sử dựng được hệ thống code trên nhiều project.

Request:

• Tuân thủ attribute convention
• Thống nhất một danh từ cho một attribute cụ thể
• Đối với những attribute có dữ liệu gửi lên không phải là những kiểu dữ liệu cơ bản (số hoặc chữ) thì ta sẽ dùng json để biểu diễn dữ liệu của attribute đó.
• Quy tắc sử dủng HTTP parameter và Form-data tương ứng với mỗi HTTP method:

Response:

HTTP code thường dùng:

1. 200 : Success
2. 400 : Bad request — dữ liệu gửi lên không hợp lệ
3. 401 : Unauthorized — user chưa được xác thực và truy cập vào resource yêu cầu phải xác thực
4. 403: Forbidden — user không có quyền truy cập vào resource
5. 404: Not found — không tồn tại resource
6. 500: Internal Server Error — có lỗi xẩy ra trong hệ thống

Đối với success response:

HTTP Code: 200
{
    data:{}
}

hoặc

HTTP Code: 200
{
    data:[]
}

• Ta luôn lấy dữ liệu trong field “data”, tuỳ từng trường hợp thì data có thể là một object hoặc một mảng object

Đối với error response:

HTTP Code != 200
{
    "error":
    {
        "user_message": "internal server error",
        "internal_message": "null pointer exception in ........",
        "code":1,
        "trace_id": "xxxxxxxxxxxxxx"
    }
    
}

• userMessage: message lỗi trả về.
• internal_message: message chi tiết của lỗi phục vụ quá trình fix bug.
• code: system error code theo chuẩn của microsoft (tri tiết tại đây).
• trace_id: là reuqest id, phục vụ cho quá trình fix bug.