Lỗi API REST trả về các thực tiễn tốt [đã đóng]

Tôi đang tìm kiếm hướng dẫn về các thực tiễn tốt khi trả về lỗi từ API REST. Tôi đang làm việc trên một API mới vì vậy tôi có thể thực hiện bất kỳ hướng nào ngay bây giờ. Hiện tại loại nội dung của tôi là XML, nhưng tôi dự định hỗ trợ JSON trong tương lai.

Bây giờ tôi đang thêm một số trường hợp lỗi, ví dụ như một khách hàng cố gắng thêm tài nguyên mới nhưng đã vượt quá dung lượng lưu trữ của anh ta. Tôi đã xử lý một số trường hợp lỗi nhất định với mã trạng thái HTTP (401 để xác thực, 403 cho ủy quyền và 404 cho URI yêu cầu xấu đơn giản). Tôi đã xem qua các mã lỗi HTTP may mắn nhưng không có phạm vi 400-417 nào có vẻ đúng để báo cáo các lỗi cụ thể của ứng dụng. Vì vậy, lúc đầu, tôi đã cố gắng trả lại lỗi ứng dụng của mình với 200 OK và một tải trọng XML cụ thể (nghĩa là trả cho chúng tôi nhiều hơn và bạn sẽ nhận được dung lượng lưu trữ mà bạn cần!) Nhưng tôi đã dừng lại để suy nghĩ về nó và nó dường như có hiệu lực (/ nhún vai trong kinh hoàng). Bên cạnh đó, có cảm giác như tôi đang chia các phản hồi lỗi thành các trường hợp riêng biệt, vì một số là mã trạng thái http được điều khiển và một số khác là hướng nội dung.

Vậy các khuyến nghị của ngành là gì? Các thực tiễn tốt (vui lòng giải thích lý do tại sao!) Và cũng như vậy, từ máy khách POV, cách xử lý lỗi nào trong API REST giúp mã máy khách dễ dàng hơn?

Vì vậy, lúc đầu, tôi đã cố gắng trả lại lỗi ứng dụng của mình với 200 OK và một tải trọng XML cụ thể (nghĩa là trả cho chúng tôi nhiều hơn và bạn sẽ nhận được dung lượng lưu trữ mà bạn cần!) Nhưng tôi đã dừng lại để suy nghĩ về nó và nó dường như có hiệu lực (/ nhún vai trong kinh hoàng).

Tôi sẽ không trả lại 200 trừ khi thực sự không có gì sai với yêu cầu. Từ RFC2616 , 200 có nghĩa là "yêu cầu đã thành công."

Nếu vượt quá dung lượng lưu trữ của khách hàng (vì bất kỳ lý do gì), tôi sẽ trả lại 403 (Bị cấm):

Máy chủ hiểu yêu cầu, nhưng từ chối thực hiện nó. Ủy quyền sẽ không giúp đỡ và yêu cầu KHÔNG NÊN lặp lại. Nếu phương thức yêu cầu không phải là CHÍNH và máy chủ muốn công khai lý do tại sao yêu cầu chưa được thực hiện, thì NÊN mô tả lý do từ chối trong thực thể. Nếu máy chủ không muốn cung cấp thông tin này cho khách hàng, mã trạng thái 404 (Không tìm thấy) có thể được sử dụng thay thế.

Điều này cho khách hàng biết rằng yêu cầu đã ổn, nhưng nó đã thất bại (điều mà 200 không thực hiện được). Điều này cũng cung cấp cho bạn cơ hội để giải thích vấn đề (và giải pháp của nó) trong cơ thể phản hồi.

Những điều kiện lỗi cụ thể khác bạn đã có trong tâm trí?

Một tài nguyên tuyệt vời để chọn mã lỗi HTTP chính xác cho API của bạn: http://www.codetinkerer.com/2015/12/04/ch rủi-an-http-status-code.html

Một đoạn trích từ bài báo:

Bắt đầu từ đâu:

2XX / 3XX:

4XX:

5XX:

Lựa chọn chính là bạn có muốn coi mã trạng thái HTTP là một phần của API REST hay không.

Cả hai cách đều hoạt động tốt. Tôi đồng ý rằng, nói đúng ra, một trong những ý tưởng của REST là bạn nên sử dụng mã Trạng thái HTTP như một phần của API của mình (trả lại 200 hoặc 201 cho một hoạt động thành công và 4xx hoặc 5xx tùy thuộc vào các trường hợp lỗi khác nhau.) Tuy nhiên , không có cảnh sát REST. Bạn có thể làm những gì bạn muốn. Tôi đã thấy các API không phải REST quá lớn được gọi là "RESTful".

Tại thời điểm này (tháng 8 năm 2015) tôi khuyên bạn nên sử dụng mã Trạng thái HTTP như một phần của API. Bây giờ dễ dàng hơn để xem mã trả về khi sử dụng các khung công tác so với trước đây. Đặc biệt, giờ đây dễ dàng hơn để thấy trường hợp trả lại không phải 200 và cơ thể của các phản hồi không 200 so với trước đây.

Mã trạng thái HTTP là một phần của api của bạn

1. Bạn sẽ cần cẩn thận chọn mã 4xx phù hợp với điều kiện lỗi của mình. Bạn có thể bao gồm phần còn lại, xml hoặc tin nhắn văn bản dưới dạng tải trọng bao gồm mã phụ và nhận xét mô tả.

2. Các máy khách sẽ cần sử dụng khung phần mềm cho phép chúng lấy mã trạng thái cấp HTTP. Thường làm có thể, không phải lúc nào cũng thẳng thắn.

3. Các máy khách sẽ phải phân biệt giữa các mã trạng thái HTTP chỉ ra lỗi giao tiếp và mã trạng thái của riêng bạn cho biết sự cố ở cấp ứng dụng.

Mã trạng thái HTTP KHÔNG phải là một phần của api của bạn

1. Mã trạng thái HTTP sẽ luôn là 200 nếu ứng dụng của bạn nhận được yêu cầu và sau đó được trả lời (cả trường hợp thành công và lỗi)

2. TẤT CẢ các câu trả lời của bạn nên bao gồm thông tin "phong bì" hoặc "tiêu đề". Điển hình như:

   phong bì_ver: 1.0
   trạng thái: # sử dụng bất kỳ mã nào bạn thích. Dự trữ mã để thành công.
   tin nhắn: "ok" # Một chuỗi con người phản ánh mã. Hữu ích cho việc gỡ lỗi.
   data: ... # Dữ liệu của phản hồi, nếu có.

3. Phương pháp này có thể dễ dàng hơn cho khách hàng vì trạng thái cho phản hồi luôn ở cùng một vị trí (không cần mã phụ), không giới hạn mã, không cần tìm nạp mã trạng thái cấp HTTP.

Đây là một bài đăng với ý tưởng tương tự: http://yuiblog.com/blog/2008/10/15/datitable-260-part-one/

Các vấn đề chính:

1. Hãy chắc chắn bao gồm số phiên bản để sau này bạn có thể thay đổi ngữ nghĩa của api nếu cần.

2. Tài liệu ...

Hãy nhớ rằng có nhiều mã trạng thái hơn các mã được xác định trong HTTP / 1.1 RFC, sổ đăng ký IANA có tại http://www.iana.org/assignments/http-status-codes . Đối với trường hợp bạn đề cập mã trạng thái 507 nghe có vẻ đúng.

Như những người khác đã chỉ ra, có một thực thể phản hồi trong mã lỗi là hoàn toàn được phép.

Hãy nhớ rằng lỗi 5xx là phía máy chủ, hay còn gọi là máy khách không thể thay đổi bất cứ điều gì thành yêu cầu của nó để thực hiện yêu cầu. Nếu vượt quá hạn ngạch của khách hàng, đó chắc chắn không phải là lỗi máy chủ, vì vậy nên tránh 5xx.

Có hai loại lỗi. Lỗi ứng dụng và lỗi HTTP. Các lỗi HTTP chỉ là để cho trình xử lý AJAX của bạn biết rằng mọi thứ đã ổn và không nên được sử dụng cho bất kỳ điều gì khác.

5xx Lỗi máy chủ

500 Internal Server Error
501 Not Implemented
502 Bad Gateway
503 Service Unavailable
504 Gateway Timeout
505 HTTP Version Not Supported
506 Variant Also Negotiates (RFC 2295 )
507 Insufficient Storage (WebDAV) (RFC 4918 )
509 Bandwidth Limit Exceeded (Apache bw/limited extension)
510 Not Extended (RFC 2774 )

2xx thành công

200 OK
201 Created
202 Accepted
203 Non-Authoritative Information (since HTTP/1.1)
204 No Content
205 Reset Content
206 Partial Content
207 Multi-Status (WebDAV)

Tuy nhiên, cách bạn thiết kế lỗi ứng dụng thực sự phụ thuộc vào bạn. Stack Overflow ví dụ gửi ra một đối tượng với response, datavà messagetài sản. Phản hồi tôi tin có chứa truehoặc falseđể cho biết liệu thao tác có thành công hay không (thường là cho các thao tác ghi). Dữ liệu chứa tải trọng (thường dành cho các hoạt động đọc) và thông báo chứa bất kỳ siêu dữ liệu bổ sung hoặc thông báo hữu ích nào (chẳng hạn như thông báo lỗi khi responsecó false).

Tôi biết điều này là rất muộn cho bữa tiệc, nhưng bây giờ, vào năm 2013, chúng tôi có một vài loại phương tiện để xử lý lỗi theo kiểu phân tán (RESTful) phổ biến. Xem "vnd.error", application / vnd.error + json ( https://github.com/blongden/vnd.error ) và "Chi tiết vấn đề cho API HTTP", ứng dụng / vấn đề + json ( https: // tools. ietf.org/html/draft-nottingham-http-pro Hiệu-05 ).

Đã đồng ý. Triết lý cơ bản của REST là sử dụng cơ sở hạ tầng web. Mã trạng thái HTTP là khung nhắn tin cho phép các bên liên lạc với nhau mà không làm tăng tải trọng HTTP. Chúng đã được thiết lập các mã phổ quát truyền đạt trạng thái phản hồi và do đó, để thực sự RESTful, các ứng dụng phải sử dụng khung này để truyền đạt trạng thái phản hồi.

Gửi phản hồi lỗi trong phong bì HTTP 200 là sai lệch và buộc khách hàng (người tiêu dùng api) phân tích thông điệp, rất có thể theo cách không chuẩn hoặc độc quyền. Điều này cũng không hiệu quả - bạn sẽ buộc khách hàng của mình phân tích tải trọng HTTP mỗi lần để hiểu trạng thái phản hồi "thực". Điều này làm tăng xử lý, thêm độ trễ và tạo môi trường cho khách hàng mắc lỗi.

Mô hình hóa api của bạn trên 'thực tiễn tốt nhất' hiện tại có thể là cách để đi. Ví dụ: đây là cách Twitter xử lý mã lỗi https://developer.twitter.com/en/docs/basics/response-codes

Hãy bám vào ngữ nghĩa của giao thức. Sử dụng 2xx cho các phản hồi thành công và 4xx, 5xx cho các phản hồi lỗi - có thể là ngoại lệ kinh doanh của bạn hoặc khác. Đã sử dụng 2xx cho bất kỳ phản hồi nào là trường hợp sử dụng dự định trong giao thức, họ sẽ không có mã trạng thái khác ở vị trí đầu tiên.

Đừng quên các lỗi 5xx cũng như các lỗi ứng dụng.

Trong trường hợp này thì khoảng 409 (Xung đột)? Điều này giả định rằng người dùng có thể khắc phục sự cố bằng cách xóa các tài nguyên được lưu trữ.

Nếu không, 507 (không hoàn toàn tiêu chuẩn) cũng có thể hoạt động. Tôi sẽ không sử dụng 200 trừ khi bạn sử dụng 200 cho các lỗi nói chung.

Nếu vượt quá hạn ngạch máy khách, đó là lỗi máy chủ, hãy tránh 5xx trong trường hợp này.