API REST có nên trả về Lỗi 500 máy chủ nội bộ để chỉ ra rằng truy vấn tham chiếu đến một đối tượng không tồn tại không?

Tôi đang làm việc với API REST nằm trên máy chủ xử lý dữ liệu cho vô số thiết bị IoT.

Nhiệm vụ của tôi là truy vấn máy chủ bằng API để thu thập thông tin hiệu suất cụ thể về các thiết bị đã nói.

Trong một trường hợp, tôi có được danh sách các thiết bị khả dụng và số nhận dạng tương ứng của chúng, sau đó truy vấn máy chủ để biết thêm chi tiết bằng cách sử dụng các số nhận dạng đó (GUID).

Máy chủ đang trả về 500 Internal Server Errormột truy vấn cho một trong những ID đó. Trong ứng dụng của tôi, một ngoại lệ được đưa ra và tôi không thấy chi tiết về lỗi. Nếu tôi kiểm tra phản hồi chặt chẽ hơn với Postman , tôi có thể thấy rằng máy chủ đã trả về JSON trong phần thân có chứa:

errorMessage: "This ID does not exist".

Bỏ qua thực tế là máy chủ đã cung cấp ID để bắt đầu - đó là một vấn đề riêng cho nhà phát triển.

API REST có nên trả về một 500 Internal Server Errorbáo cáo rằng truy vấn tham chiếu đến một đối tượng không tồn tại không? Theo suy nghĩ của tôi, các mã phản hồi HTTP nên tham khảo đúng trạng thái của lệnh gọi REST, hơn là các cơ chế bên trong của API. Tôi mong đợi một 200 OKphản hồi có chứa lỗi và mô tả, sẽ thuộc quyền sở hữu của API được đề cập.

Nó xảy ra với tôi rằng có một sự khác biệt tiềm năng trong kỳ vọng tùy thuộc vào cách gọi lệnh REST được cấu trúc.

Hãy xem xét các ví dụ sau:

1. http://example.com/restapi/deviceinfo?id=123
2. http://example.com/restapi/device/123/info

Trong trường hợp đầu tiên, ID thiết bị được truyền dưới dạng biến GET. 404 hoặc 500 sẽ chỉ ra rằng đường dẫn ( /restapi/deviceinfo) không được tìm thấy hoặc dẫn đến lỗi máy chủ.

Trong trường hợp thứ hai, ID thiết bị là một phần của URL. Tôi sẽ hiểu nhiều hơn về a 404 Not Found, nhưng vẫn có thể tranh luận dựa trên phần nào của đường dẫn được hiểu là các biến so với điểm cuối.

Tôi nghĩ rằng phản hồi 404 là kết hợp ngữ nghĩa tốt nhất ở đây, vì không tìm thấy tài nguyên mà bạn đang cố gắng tìm kiếm (như được đại diện bởi URI được sử dụng cho truy vấn). Trả lại một trọng tải lỗi trong cơ thể là hợp lý, nhưng không bắt buộc.

Theo RFC 2616 , định nghĩa của mã trạng thái 404 là:

10.4.5 404 Không tìm thấy
Máy chủ không tìm thấy bất cứ thứ gì khớp với URI yêu cầu. Không có dấu hiệu nào được đưa ra cho dù điều kiện là tạm thời hay vĩnh viễn. Mã trạng thái 410 (Đã qua) NÊN được sử dụng nếu máy chủ biết, thông qua một số cơ chế có thể định cấu hình bên trong, rằng tài nguyên cũ không có sẵn vĩnh viễn và không có địa chỉ chuyển tiếp. Mã trạng thái này thường được sử dụng khi máy chủ không muốn tiết lộ chính xác lý do tại sao yêu cầu bị từ chối hoặc khi không có phản hồi nào khác được áp dụng.

Tôi sẽ sử dụng các ví dụ của bạn.

http://example.com/restapi/deviceinfo?id=123

Nếu điểm cuối trả về một mảng json , sự lựa chọn tốt nhất là 200 OKvới một mảng trống nếu không tìm thấy kết quả.

Nếu điểm cuối được thiết kế để trả về một kết quả duy nhất , thì sự lựa chọn của tôi sẽ là 404 NOT FOUND, bởi vì, đối với tôi, cú pháp đúng cho loại điểm cuối này là : http://example.com/restapi/deviceinfo/123. Tôi thường chỉ sử dụng param param để lọc và khi điểm cuối của tôi trả về một mảng.

http://example.com/restapi/device/123/info

Tôi nghĩ rằng câu hỏi này đã được trả lời ở đây . POST hoặc GET, sự lựa chọn tốt hơn dường như 404 NOT FOUNDvì tài nguyên 123không được tìm thấy.

Trong cả hai trường hợp, tôi không thể thấy sự cần thiết phải giải thích lý do yêu cầu không được hoàn thành. Thông tin yêu cầu và mã HTTP đã giải thích lý do tại sao.

HTTP 404 là chính xác, bởi vì máy chủ hiểu tài nguyên mà khách hàng đang yêu cầu, nhưng nó không có tài nguyên đó.

Thực tế là bạn đang làm việc với "API REST" là chìa khóa. API sẽ hoạt động giống như nó đang thực hiện Chuyển giao trạng thái giới thiệu, không thực hiện chức năng. (Chắc chắn, thuật ngữ "REST" đã có nghĩa rộng hơn, nhưng bạn vẫn có thể sử dụng nghĩa đen của nó để có hiệu quả tốt ở đây.) Khách hàng đã yêu cầu trạng thái của tài nguyên được mô tả bởi URL http://example.com/restapi/device/123/info. Một chuỗi truy vấn ( /deviceinfo?id=123) sẽ không thay đổi tình hình. Máy chủ biết bạn đang yêu cầu chuyển trạng thái của thiết bị 123, nhưng nó không nhận ra đó là tài nguyên đã biết. Do đó HTTP 404.

Các phản ứng có thể khác được thảo luận ở đây cũng có ý nghĩa cụ thể:

• HTTP 200- Chúng tôi có nhà nước cho bạn; đó là trong cơ thể phản ứng.
• HTTP 204- Chúng tôi có nhà nước cho bạn; nó trống
• HTTP 400- Chúng tôi không thể nói bạn đang hỏi về tài nguyên nào. Sửa URL của bạn.
• HTTP 500- Chúng tôi gặp trục trặc. Không phải lỗi của bạn.

Xem RFC 2616 giây. 10 khi thích hợp.

Một lỗi 5xx thường được sử dụng để chỉ ra rằng máy chủ đã gặp lỗi và không thể hoàn thành yêu cầu. Nếu máy chủ nhận yêu cầu, có thể phân tích thành công yêu cầu đó và sau đó thực hiện công việc đó, điều đó sẽ không trả về lỗi 5xx.

Tôi không chắc chắn nếu có bất kỳ loại quy ước nào về việc trả lại nếu truy vấn không mang lại kết quả. Tôi đã thấy cả những gì bạn mô tả (200 với phần thân có chứa thông điệp) cũng như 404 cho biết kết quả không được tìm thấy. 200 có lẽ có ý nghĩa nhất - yêu cầu được hoàn thành thành công và không có vấn đề gì với yêu cầu của khách hàng hoặc trong quá trình máy chủ xử lý yêu cầu. Một cơ thể có thể gửi một thông điệp cho khách hàng.

Tôi sẽ coi cả hai ví dụ của bạn ( http://example.com/restapi/deviceinfo?id=123và http://example.com/restapi/device/123/info) giống nhau - 123là một tham số. Cả hai trường hợp là những cách khác nhau để cấu trúc một yêu cầu để lấy thông tin thiết bị cho một thiết bị có ID 123.

Đầu tiên, tôi sẽ xem xét ủy quyền và xác thực. Nếu người dùng không có quyền thích hợp, tôi sẽ trả lại 403 hoặc 401 nếu phù hợp. Mặc dù được gọi là "Không được phép", nhưng tôi hiểu rằng 401 liên quan nhiều hơn đến xác thực và 403 là về việc không được phép hoặc bị từ chối. Tuy nhiên, tôi sẽ không quá kén chọn nếu bạn chỉ muốn dính vào 403 cho tất cả các lỗi xác thực và ủy quyền.

Sau đó, tôi sẽ xử lý ID. Dựa trên ví dụ của bạn, có vẻ như đó là ID số. Nếu giá trị không phải là số được cung cấp, tôi sẽ trả về 400. Nếu tham số có thể là định danh thiết bị hợp lệ, thì tôi sẽ tiếp tục xử lý. Nếu có các đối số khác, chúng cũng sẽ được kiểm tra ở đây. Tôi hy vọng cơ quan phản hồi có chứa thông tin phù hợp về lý do tại sao yêu cầu xấu.

Nếu tất cả các tham số là hợp lệ, tôi sẽ bắt đầu xử lý yêu cầu. Nếu hệ thống hoặc bất kỳ sự phụ thuộc nào (cơ sở dữ liệu, dịch vụ của bên thứ ba, dịch vụ nội bộ khác) không khả dụng, tôi sẽ trả lại mã 5xx - 503 sẽ cụ thể, nhưng 500 cũng có thể được chấp nhận. Trong cả hai trường hợp, tôi sẽ trả lại một cơ thể với các chi tiết bổ sung. Hãy xem xét rằng nếu một phụ thuộc bên ngoài báo cáo Hết thời gian yêu cầu 408, tôi sẽ ăn nó và trả lại 500 cho khách hàng của mình, cho phép khách hàng nhận được 408 chỉ khi yêu cầu đến hệ thống của tôi hết hạn. Nếu hệ thống có thể hoàn thành yêu cầu, tôi sẽ trả lại 200 và cơ thể thích hợp.

204 có thể hữu ích trong một số trường hợp, nhưng nó ngăn cản bạn gửi một cơ quan phản hồi. Đặc biệt là trong cài đặt API, việc gửi một cơ quan phản hồi với thông tin có thể được đưa vào cơ chế ghi nhật ký hoặc báo cáo có vẻ như là quyết định đúng đắn trong hầu hết các trường hợp.

Lần duy nhất 404 sẽ được trả về là nếu máy chủ không có /deviceinfođiểm cuối hoặc /device/:id/infođiểm cuối.

Tôi sẽ không xem xét một ID không được tìm thấy giống như tài nguyên không được tìm thấy. Tài nguyên là thông tin thiết bị cho một thiết bị cụ thể (trong ví dụ của bạn). Trả lại 404 có nghĩa là tài nguyên (thông tin thiết bị) không tồn tại. Một 200 với một cơ thể thích hợp có nghĩa là hệ thống thực sự có thể cung cấp thông tin thiết bị. Có thể có hoặc không có một thiết bị có ID được chỉ định.

Một lỗi HTTP 500-series cho thấy sự cố máy chủ. Ngoài 501 Not Implementedvà 505 HTTP Version Not Supported, việc sử dụng các mã lỗi này mang hàm ý rằng thử lại yêu cầu sau đó có thể thành công (mặc dù chỉ 503 Service Unavailablenêu rõ điều này). Lý tưởng nhất là máy chủ không bao giờ nên tạo một trong các mã này, mặc dù việc không thể viết phần mềm không có lỗi và cung cấp cho máy chủ tài nguyên vô hạn có nghĩa là thỉnh thoảng bạn sẽ cần chúng.

Đối với kết quả "đối tượng không tồn tại", có lẽ bạn nên trả về 404 Not Found(khi yêu cầu dành cho một đối tượng theo tên) hoặc 200 Successvới phần thân kết quả trống (khi tìm kiếm đối tượng theo thuộc tính). 204 No Contentcó vẻ hấp dẫn, nhưng tôi chỉ sử dụng nó cho các tình huống thiếu cơ thể phản ứng là kết quả mong đợi.

Là khách hàng của API của bạn, khi tôi thực hiện một trong các cuộc gọi sau:

1. http://example.com/restapi/deviceinfo?id=123
2. http://example.com/restapi/device/123/info

Tôi hy vọng sẽ lấy lại một (đại diện) một DeviceInfođối tượng (hoặc một loại cụ thể nào đó, cho dù đó là loại chính thức hay chỉ là một cái gì đó phù hợp với quy ước "loại vịt" được ghi lại). Tôi muốn một 200trạng thái có nghĩa là tôi thực sự có một, và tôi có thể tiếp tục và sử dụng nó.

Đối với API REST, tôi nghĩ 400 và 500 mã trạng thái là một cái gì đó giống như ngoại lệ. Bạn sử dụng chúng để cho biết khi nào bạn không thể trả lại phản hồi "bình thường" cho yêu cầu bạn đã nhận được, vì vậy khách hàng sẽ cần phải làm một điều gì đó đặc biệt thay vì xử lý thông tin mà họ mong muốn nhận được.

Điều này có nghĩa là, với tư cách là người tiêu dùng API, tôi có thể sử dụng một số loại chức năng gọi lại được kiểm tra để lấy phản hồi hoặc ném ngoại lệ. Thật tuyệt; logic thông thường của tôi có thể là mã đường thẳng và tôi có thể tổ chức xử lý lỗi giống như cách tôi làm trong mã cục bộ. 404 bất ngờ sẽ biểu hiện là ngoại lệ "không tìm thấy tài nguyên" mà không cần tôi phải làm gì cả, không phải là lỗi "thuộc tính bị thiếu" khi tôi xử lý sau đó { errorMessage: "Device 123 not found" }như thể nó là một DeviceInfođối tượng.

Nếu bạn cho rằng điểm cuối http://example.com/restapi/deviceinfo được tìm thấy và chỉ có điểm id=123cuối thì không trả về 200 với thông báo lỗi trong phần thân, thì bạn đang tạo chính xác loại sự cố giao diện giống như các hàm C có thể trả về kết quả chính xác hoặc mã lỗi hoặc phương pháp chỉ ra sự cố bằng cách tự ý trả vềnull. Sẽ tốt hơn nhiều khi người dùng giao diện của bạn có các lỗi được chỉ định thông qua kênh "riêng biệt" với lợi nhuận thông thường. Điều đó cũng áp dụng ở đây, mặc dù các phản hồi HTTP 200, 404 và 500 là cùng một kênh theo quan điểm cấp thấp. Chúng được chuẩn hóa và dễ dàng phân biệt để khung máy khách REST của tôi có thể dễ dàng bật các trạng thái đó để biến chúng thành các cấu trúc phù hợp trong ngôn ngữ của tôi; để làm điều tương tự với lớp JSON (nơi bạn luôn nói 200 và đưa cho tôi một DeviceInfohoặc một thông báo lỗi) Tôi cần nhúng một số kiến ​​thức về các lược đồ JSON mà bạn sử dụng.

Vì vậy, chỉ sử dụng 200 khi bạn có thể trả về giá trị hợp lệ của loại dự kiến ​​(đó là lý do tại sao http://example.com/restapi/search-devices?colour=bluecó thể trả về 200 với mảng trống nếu không có thiết bị màu xanh; mảng trống là mảng hợp lệ và câu trả lời hợp lý cho yêu cầu "Tôi muốn các chi tiết của tất cả các thiết bị màu xanh "). Nếu bạn không thể, hãy sử dụng mã trạng thái không phải 200 phù hợp nhất. Mặc dù "thiết bị 123 không tồn tại" là phản hồi chính xác cho "cung cấp cho tôi thông tin chi tiết về thiết bị 123" và không phải là lỗi cho máy chủ , nhưng đó là một ngoại lệ đối với mong muốn của khách hàng rằng họ sẽ lấy lại DeviceInfovà nên không được truyền đạt như một phản hồi "đây là những gì bạn yêu cầu" bình thường.

Bạn có thể sử dụng lỗi 422 Thực thể không thể xử lý để phân biệt với 404 không tìm thấy . 422 có nghĩa là máy chủ hiểu yêu cầu nhưng nó không thể đưa ra phản hồi thích hợp. Tôi đang sử dụng mã này trong các tình huống tương tự.

Lỗi 500 thường chỉ ra rằng yêu cầu đã làm hỏng chương trình phía máy chủ; trong môi trường doanh nghiệp, các lỗi này được coi là một quả trứng ở mặt và đang được tránh.

Lỗi 4xx sẽ báo hiệu cho lập trình viên rằng điểm cuối API (tài nguyên) không tồn tại. Do đó, khi đã đạt đến điểm cuối thích hợp, mọi xử lý lỗi từ thời điểm đó trở đi là trách nhiệm lập trình viên của API cần được xử lý một cách duyên dáng, tức là với thông báo lỗi phản hồi 200.

Mặc dù w3 lưu ý rằng 404 được sử dụng khi không có phản hồi nào khác được áp dụng , nhưng đây có phải là phản hồi 204 (Không có nội dung) phù hợp không? Yêu cầu có hiệu lực từ quan điểm xử lý và máy chủ đã xử lý yêu cầu và có kết quả. Đó là một thành công, dựa vào phản hồi 2xx. Không có nội dung cho yêu cầu cụ thể này nên 204 nói với người dùng rằng không có gì sai với truy vấn của họ nhưng không có gì ở đó.

Bạn cũng có thể đưa ra một trường hợp yếu rằng 409 (Xung đột) là một phản ứng thích hợp. Mặc dù 409 thường được sử dụng cho POST, nhưng nó nói

Yêu cầu không thể được hoàn thành do xung đột với trạng thái hiện tại của tài nguyên. Mã này chỉ được phép trong các tình huống mà người dùng dự kiến ​​có thể giải quyết xung đột và gửi lại yêu cầu. Cơ quan phản hồi NÊN bao gồm đủ thông tin để người dùng nhận ra nguồn gốc của xung đột. Lý tưởng nhất, thực thể phản hồi sẽ bao gồm đủ thông tin cho người dùng hoặc tác nhân người dùng để khắc phục sự cố; tuy nhiên, điều đó có thể là không thể và không bắt buộc.

có thể cho rằng sự không tồn tại của id được yêu cầu là xung đột ở đây và việc trả về trong thông báo rằng không có id nào như vậy tồn tại trong hệ thống là đủ thông tin để người dùng nhận ra và khắc phục xung đột.

Các câu trả lời khác bao gồm nó, nhưng tôi chỉ muốn chỉ ra rằng một lỗi 500-series có nghĩa là "Tôi đã làm hỏng". Trong trường hợp này, "I" có nghĩa là API, do đó, lỗi máy chủ chưa được xử lý hoặc tương tự. Một lỗi 400-series có nghĩa là "bạn đã làm hỏng" - người gọi API đã gửi một cái gì đó không chính xác.

Những người dùng khác đã cung cấp câu trả lời hợp lệ cho những việc cần làm nếu bạn muốn đi theo cuốn sách.

Tuy nhiên tôi sẽ đề nghị rằng bạn đang đọc quá nhiều vào RESTfulness và hoàn toàn nghiêm túc hơn đối với nó.

REST là một giao thức nguy hiểm, bởi vì nếu bạn muốn đi theo cuốn sách trong khi sử dụng nó, thì nó buộc cả máy khách và máy chủ phải được xây dựng có kiến ​​thức cụ thể về thực tế rằng chúng đang giao tiếp qua REST, vì vậy về bản chất là giao thức truyền thông cụ thể sử dụng không thể được trừu tượng hóa.

Có một cách tiếp cận khác: hoàn toàn tránh khỏi RESTfulness, và sử dụng nó như một giao thức giao tiếp và không có gì khác. Điều này có nghĩa là các phản hồi duy nhất cần được trả về là "HTTP 200 OK" và "Lỗi máy chủ nội bộ HTTP 500" vì theo như giao thức liên lạc, mọi nỗ lực giao tiếp chỉ có thể có hai kết quả: yêu cầu đã thành công giao cho máy chủ, hoặc không.

Điều gì xảy ra sau khi giao hàng, không phải là việc của giao thức truyền thông. Vì vậy, một khi máy chủ đã nhận được yêu cầu thành công và bắt đầu xử lý nó, nhiều lỗi có thể xảy ra, nhưng đây đều là những lỗi cụ thể của ứng dụng mà không phải là vấn đề kinh doanh của giao thức truyền thông. Chúng nên được truyền đạt trong phạm vi tải trọng của một phản hồi có vẻ hoàn toàn thành công theo như giao thức truyền thông biết.

Vì vậy, điểm mấu chốt là, tôi khuyên bạn nên trả lại "HTTP 200 OK" và trong tải trọng phản hồi ("nội dung phản hồi" theo cách nói HTTP) có mã lỗi dành riêng cho ứng dụng có nội dung "Không tìm thấy ID" hoặc bất cứ điều gì.