Thông báo lỗi còn lại trong Tiêu đề HTTP hoặc Nội dung phản hồi?

Question 1

Tôi có một dịch vụ REST tiếp xúc với các ứng dụng khách iPhone và Android. Hiện tại tôi làm theo các mã HTTP 200, 400, 401, 403, 404, 409, 500, v.v.

Câu hỏi của tôi là nơi được khuyến nghị đặt lý do / mô tả / nguyên nhân gây ra lỗi là ở đâu? Việc API REST luôn có Lý do tùy chỉnh trong tiêu đề như vậy có hợp lý hơn không?

< HTTP/1.1 400 Bad Request - Missing Required Parameters.
< Date: Thu, 20 Dec 2012 01:09:06 GMT
< Server: Apache/2.2.22 (Ubuntu)
< Connection: close
< Transfer-Encoding: chunked

Hay tốt hơn là có nó trong Cơ quan phản hồi thông qua JSON?

< HTTP/1.1 400 Bad Request
< Date: Thu, 20 Dec 2012 01:09:06 GMT
< Server: Apache/2.2.22 (Ubuntu)
< Connection: close
< Transfer-Encoding: chunked
< Content-Type: application/json
{ "error" : "Missing Required Parameters" }

Question 2

Trích dẫn từ đặc tả HTTP cho mã lỗi 400.x:

Loại mã trạng thái 4xx dành cho các trường hợp khách hàng dường như đã mắc lỗi. Ngoại trừ khi phản hồi yêu cầu HEAD, máy chủ NÊN bao gồm một thực thể chứa giải thích về tình huống lỗi và đó là tình trạng tạm thời hay vĩnh viễn. Các mã trạng thái này có thể áp dụng cho bất kỳ phương thức yêu cầu nào. Tác nhân người dùng NÊN hiển thị bất kỳ thực thể nào được bao gồm cho người dùng.

Cách tốt nhất là bao gồm thông báo lỗi dưới dạng một thực thể trong phần nội dung của phản hồi HTTP - có thể là JSON, văn bản thuần túy, HTML được định dạng hoặc bất kỳ định dạng nào khác mà bạn có thể muốn sử dụng.

Question 3

Tốt hơn là có các chi tiết lỗi trong cơ thể. Hơn nữa, nhiều (hầu hết / gần như tất cả, ví dụ: WSGI) máy chủ và máy khách không hỗ trợ thay đổi tên của mã lỗi - coi chúng như các cặp cố định (vì vậy, ví dụ: 400 luôn là "Yêu cầu sai" chứ không phải "Yêu cầu xấu - Bạn Quên xác định ID người dùng "). Ngay cả khi chúng không bị vỡ, chúng sẽ không quan tâm đến tên đặc biệt của bạn cho mã lỗi cụ thể.

Question 4

Lỗi không thuộc về cơ thể. Nó nằm trong tiêu đề Cảnh báo.

Tiêu đề HTTP chung cảnh báo chứa thông tin về các sự cố có thể xảy ra với trạng thái của thư.

Tài liệu tham khảo

Question 5

Tôi luôn làm cả hai. Tôi thường đặt thông báo trạng thái thành thứ gì đó mà giao diện người dùng có thể hiển thị theo cách thân thiện với người dùng, chẳng hạn như "409 - Không thể thêm người dùng mới, họ đã tồn tại."

Sau đó, tôi bao gồm các chi tiết về các điều kiện lỗi trong phần thân dưới dạng JSON để các nhà phát triển giao diện người dùng có thể cố gắng đưa ra các lựa chọn thông minh về việc cần làm.

{
  "status": 409,
  "message": "The user <username> was already added on <when> by <who> and given the user id 12345.",
  "errors": {
    "id": 12345
  }
}