RFC 7807

Giới thiệu

Giả sử bạn có nhiều API xử lý data trong một ứng dụng. Khi 1 API xảy ra lỗi, nó sẽ trả về error code

Có thể trả theo cách này

{
	"isSuccess": "true",
	"errorDetai": "An internal server error occurred."
}

Hoặc cách này

{
	"isSuccess": "true",
	"error": {
		"errorDetai": "An internal server error occurred.",
		"errorCode": "401"
	}
}

Và còn rất nhiều cách khác nữa

Rất may là chúng ta có RFC 7807. RFC 7807 là một tiêu chuẩn Internet xác định một "problem detail" là một cách để mang theo các chi tiết lỗi có thể đọc được bằng máy trong phản hồi HTTP để tránh cần định nghĩa các định dạng phản hồi lỗi mới cho API HTTP.

Trước RFC 7807, các API HTTP thường sử dụng các định dạng phản hồi lỗi riêng lẻ. Điều này có thể gây khó khăn cho các API trong việc xử lý các lỗi, vì các API này cần phải hiểu định dạng lỗi cụ thể của mỗi API.

HTTP Code error

HTTP code error là một thông báo được gửi từ server về phía client, cho biết đã có lỗi xảy ra trong quá trình xử lý request. Mỗi code error có một ý nghĩa riêng, cung cấp thông tin về bản chất của lỗi và giúp client biết cách xử lý tiếp theo.

Chữ số đầu tiên của HTTP status code chỉ định 1 trong 5 loại phản hồi quy chuẩn. Các cụm tin nhắn được hiển thị chỉ mang tính tượng trưng, nhưng cũng có thể cung cấp bất kỳ thông tin bổ sung nào để chúng ta có thể đọc được. Trừ khi có những chỉ định khác, HTTP status code được xem như 1 phần của quy chuẩn HTTP/1.1 (RFC 7231).

Cơ Quan Cấp Số Được Ấn Định Trên Internet (tức IANA hay The Internet Assigned Numbers Authority) chính là nơi duy trì sổ đăng ký chính thức của các HTTP status code.
HTTP Code Categories

HTTP code error được phân thành 5 nhóm chính:

1. Informational responses (100–199): Chỉ ra rằng request đã được nhận và đang được xử lý. Ví dụ: 100 Continue.
2. Successful responses (200–299): Xác nhận rằng request đã được thực hiện thành công. Ví dụ: 200 OK, 201 Created.
3. Redirection messages (300–399): Yêu cầu client chuyển hướng đến một URL khác để hoàn thành request. Ví dụ: 301 Moved Permanently, 302 Found.
4. Client error responses (400–499): Chỉ ra lỗi do phía client gây ra, chẳng hạn như request không hợp lệ hoặc tài nguyên không được tìm thấy. Ví dụ: 400 Bad Request, 404 Not Found.
5. Server error responses (500–599): Xác nhận rằng server gặp lỗi và không thể thực hiện request. Ví dụ: 500 Internal Server Error, 503 Service Unavailable.

Giải thích từng nhóm:

1. Informational responses (100–199):

    100 Continue: Server đang chờ client gửi tiếp dữ liệu.
    101 Switching Protocols: Server đã chuyển sang giao thức khác.

2. Successful responses (200–299):

    200 OK: Request đã thành công và trả về dữ liệu.
    201 Created: Request đã tạo tài nguyên mới.
    202 Accepted: Request đã được nhận và đang được xử lý.
    204 No Content: Request thành công nhưng không có dữ liệu trả về.

3. Redirection messages (300–399):

    301 Moved Permanently: Tài nguyên đã được chuyển đến một URL khác.
    302 Found: Tài nguyên tạm thời được chuyển đến một URL khác.
    303 See Other: Client nên truy cập một URL khác để hoàn thành request.
    304 Not Modified: Tài nguyên chưa được thay đổi kể từ lần truy cập trước đó.

4. Client error responses (400–499):

    400 Bad Request: Request không hợp lệ.
    401 Unauthorized: Client không được phép truy cập tài nguyên.
    403 Forbidden: Client không có quyền truy cập tài nguyên.
    404 Not Found: Tài nguyên không được tìm thấy.
    405 Method Not Allowed: Server không hỗ trợ phương thức request.
    409 Conflict: Request gây ra xung đột.

5. Server error responses (500–599):

    500 Internal Server Error: Server gặp lỗi.
    501 Not Implemented: Server không thể thực hiện request.
    502 Bad Gateway: Server nhận được lỗi từ server khác.
    503 Service Unavailable: Server không thể xử lý request do quá tải.
    504 Gateway Timeout: Server không nhận được phản hồi kịp thời từ server khác.

HTTP Codes define by RFC-7231 (Source: Cheatography)

 

RFC 7807

Mục đích của đặc tả RFC 7807 là xác định các lỗi phổ biến (common error format) cho các ứng dụng khi cần đến chúng

Ví dụ

HTTP/1.1 403 Forbidden

Content-Type: application/problem+json

Content-Language: en


{

  "type": "https://myexample.com/issues/out-of-credit", 

  "title": "You do not have enough credit to book a room.", 

  "detail": "Your current balance is 30 EUR, but a room costs 50 EUR per night.",

  "instance": "/accounts/12345/errors/out-of-credit/err_instance_id=123",

  "balance": 30,

  "account": "/accounts/12345"

}

RFC 7807 giới thiệu 1 cách để standardized các report problem để báo cáo các sự cố cho máy khách. Tiêu chuẩn này định nghĩa media type là application/problem+json hoặc application/problem+xml cho XML

Một Problem JSON payload nên có ít nhất 1 property: the "type" field (➊). "type" là mã định danh duy nhất cho mã hiện tại (URN)

Dưới đây là 2 ví dụ cho thấy việc sử dụng type quan trọng như thế nào

Error 1: user name is already taken

400 BAD REQUEST
{
    "message": "A user named 'Lucy' already exists."
}

Error 2: malformed input provided

400 BAD REQUEST
{
    "message": "Field 'name' is required."
}

Nếu chúng ta định nghĩa thêm type thì sẽ xác định lỗi cụ thể là gì. Các field sau đây là optional:

• title – Ngắn gọn dễ hiểu về mã lỗi
• status – The HTTP status code được tạo ra khi xuất hiện lỗi
• detail – Giải thích cụ thể về lỗi xuất hiện
• instance – Tham chiếu URI xác định sự cố xảy ra cụ thể

Một số field extension khác có thể được thêm vào, nhưng phải đảm bảo có thể được serialize

HTTP/1.1 403 Forbidden
Content-Type: application/problem+json
Content-Language: en

{
  "type": "https://myexample.com/issues/out-of-credit", 
  "title": "You do not have enough credit to book a room.", 
  "detail": "Your current balance is 30 EUR, but a room costs 50 EUR per night.",
  "instance": "/accounts/12345/errors/out-of-credit/err_instance_id=123",
  "balance": 30,
  "account": "/accounts/12345"
}

Sử dụng Problem Details trong Azure Functions

Tham khảo

https://www.linkedin.com/pulse/rfc-7807-error-handling-standard-apis-david-rold%C3%A1n-mart%C3%ADnez

https://topdev.vn/blog/http-status-code-la-gi/

https://code-maze.com/using-the-problemdetails-class-in-asp-net-core-web-api/