Mã trạng thái HTTP nào sẽ trả về nếu nhiều hành động kết thúc với các trạng thái khác nhau?

Tôi đang xây dựng một API nơi người dùng có thể yêu cầu máy chủ thực hiện nhiều hành động trong một yêu cầu HTTP. Kết quả được trả về dưới dạng một mảng JSON, với một mục nhập cho mỗi hành động.

Mỗi hành động này có thể thất bại hoặc thành công độc lập với nhau. Chẳng hạn, hành động đầu tiên có thể thành công, đầu vào của hành động thứ hai có thể được định dạng kém và không thể xác thực và hành động thứ ba có thể gây ra lỗi không mong muốn.

Nếu có một yêu cầu cho mỗi hành động, tôi sẽ trả lại mã trạng thái lần lượt 200, 422 và 500. Nhưng bây giờ khi chỉ có một yêu cầu, tôi nên trả lại mã trạng thái nào?

Một số tùy chọn:

• Luôn trả lại 200, và cung cấp thông tin chi tiết hơn trong cơ thể.
• Có thể chỉ tuân theo quy tắc trên khi có nhiều hơn một hành động trong yêu cầu?
• Có thể trả lại 200 nếu tất cả các yêu cầu thành công, nếu không 500 (hoặc một số mã khác)?
• Chỉ cần sử dụng một yêu cầu cho mỗi hành động và chấp nhận thêm chi phí.
• Một cái gì đó hoàn toàn khác nhau?

Câu trả lời ngắn gọn, trực tiếp

Kể từ khi yêu cầu nói về thực hiện danh sách các nhiệm vụ (nhiệm vụ là nguồn lực mà chúng ta đang nói về ở đây), sau đó nếu nhóm nhiệm vụ đã được di chuyển về phía trước để thực hiện (có nghĩa là, bất kể kết quả thực hiện), sau đó nó sẽ là hợp lý rằng trạng thái phản hồi sẽ là 200 OK. Mặt khác, nếu có một vấn đề sẽ ngăn việc thực thi nhóm tác vụ, chẳng hạn như không xác thực các đối tượng tác vụ hoặc một số dịch vụ được yêu cầu không có sẵn, ví dụ, trạng thái phản hồi sẽ biểu thị lỗi đó. Trước đó, khi việc thực thi các nhiệm vụ bắt đầu, được xem là các nhiệm vụ cần thực hiện được liệt kê trong phần yêu cầu, thì tôi sẽ mong rằng các kết quả thực hiện sẽ được liệt kê trong phần phản hồi.

Câu trả lời dài, đầy triết lý

Bạn đang gặp vấn đề nan giải này bởi vì bạn đang chuyển hướng từ những gì HTTP được thiết kế cho. Bạn không tương tác với nó để quản lý tài nguyên, thay vào đó, bạn đang sử dụng nó như là phương tiện của việc gọi phương thức từ xa (không phải là rất kỳ quặc, tuy nhiên hoạt động kém mà không có sơ đồ định sẵn).

Với những điều đã nói ở trên và không có can đảm để biến câu trả lời này thành một hướng dẫn dài dòng, sau đây là sơ đồ URI phù hợp với phương pháp quản lý tài nguyên:

• /tasks
  • GET liệt kê tất cả các nhiệm vụ, phân trang
  • POST thêm một nhiệm vụ
• /tasks/task/[id]
  • GET đáp ứng với một đối tượng trạng thái của một nhiệm vụ
  • DELETE hủy bỏ / xóa một tác vụ
• /tasks/groups
  • GET liệt kê tất cả các nhóm nhiệm vụ, phân trang
  • POST thêm một nhóm nhiệm vụ
• /tasks/groups/group/[id]
  • GET đáp ứng với trạng thái của một nhóm nhiệm vụ
  • DELETE hủy bỏ / xóa nhóm nhiệm vụ

Cấu trúc này nói về tài nguyên, không phải làm gì với chúng. Những gì đang được thực hiện với các nguồn lực là mối quan tâm của một dịch vụ khác.

Một điểm quan trọng khác cần thực hiện là không nên chặn quá lâu trong trình xử lý yêu cầu HTTP. Giống như UI, giao diện HTTP phải phản hồi nhanh - trong một khoảng thời gian chậm hơn một vài bậc (vì lớp này xử lý IO).

Việc chuyển sang thiết kế giao diện HTTP quản lý chặt chẽ các tài nguyên có thể khó như việc di chuyển khỏi luồng UI khi nhấn nút. Nó yêu cầu máy chủ HTTP giao tiếp với các dịch vụ khác để thực thi các tác vụ thay vì thực thi chúng trong trình xử lý yêu cầu. Đây không phải là một triển khai nông cạn, nó là một sự thay đổi theo hướng.

Một số ví dụ về cách sử dụng lược đồ URI như vậy

Thực hiện một nhiệm vụ duy nhất và theo dõi tiến trình:

• POST /tasks với nhiệm vụ thực thi
  • GET /tasks/task/[id]cho đến khi đối tượng phản hồi completedcó giá trị dương trong khi hiển thị trạng thái / tiến trình hiện tại

Thực hiện một nhiệm vụ duy nhất và chờ hoàn thành:

• POST /tasks với nhiệm vụ thực thi
  • GET /tasks/task/[id]?awaitCompletion=truecho đến khi completedcó giá trị dương (có thể có thời gian chờ, đó là lý do tại sao điều này nên được lặp lại)

Thực hiện một nhóm nhiệm vụ và theo dõi tiến trình:

• POST /tasks/groups với nhóm các nhiệm vụ để thực hiện
  • GET /tasks/groups/group/[groupId]cho đến khi thuộc tính đối tượng phản hồi completedcó giá trị, hiển thị trạng thái nhiệm vụ riêng lẻ (ví dụ 3 nhiệm vụ hoàn thành trong số 5)

Yêu cầu thực hiện cho một nhóm nhiệm vụ và chờ hoàn thành:

• POST /tasks/groups với nhóm các nhiệm vụ để thực hiện
  • GET /tasks/groups/group/[groupId]?awaitCompletion=true cho đến khi trả lời với kết quả biểu thị sự hoàn thành (có thể có thời gian chờ, đó là lý do tại sao nên lặp lại)

Phiếu bầu của tôi sẽ được chia các nhiệm vụ này thành các yêu cầu riêng biệt. Tuy nhiên, nếu quá nhiều chuyến đi khứ hồi là một mối quan tâm, tôi đã bắt gặp mã phản hồi HTTP 207 - Đa trạng thái

Sao chép / dán từ liên kết này:

Phản hồi Đa trạng thái truyền tải thông tin về nhiều tài nguyên trong các tình huống có thể có nhiều mã trạng thái phù hợp. Phần thân phản hồi Đa trạng thái mặc định là một thực thể HTTP văn bản / xml hoặc ứng dụng / xml với phần tử gốc 'multistatus'. Các phần tử khác chứa các mã trạng thái 200, 300, 400 và 500 được tạo trong quá trình gọi phương thức. 100 mã trạng thái sê-ri KHÔNG NÊN được ghi lại trong phần tử XML 'phản hồi'.

Mặc dù '207' được sử dụng làm mã trạng thái phản hồi tổng thể, người nhận cần tham khảo nội dung của cơ quan phản hồi đa tầng để biết thêm thông tin về thành công hay thất bại của việc thực thi phương thức. Phản ứng CÓ THỂ được sử dụng trong thành công, thành công một phần và cả trong các tình huống thất bại.

Mặc dù đa trạng thái là một tùy chọn, tôi sẽ trả lại 200 (Tất cả đều ổn) nếu tất cả các yêu cầu thành công và một lỗi (500 hoặc có thể là 207) nếu không.

Trường hợp tiêu chuẩn thường là 200 - mọi thứ đều hoạt động. Và khách hàng chỉ nên kiểm tra điều đó. Và chỉ khi trường hợp lỗi xảy ra, bạn mới có thể trả về 500 (hoặc 207). Tôi nghĩ rằng 207 là một lựa chọn hợp lệ trong trường hợp có ít nhất một lỗi, nhưng nếu bạn thấy toàn bộ gói là một giao dịch, bạn cũng có thể gửi 500. - Khách hàng sẽ muốn diễn giải thông báo lỗi theo bất kỳ cách nào.

Tại sao không luôn luôn gửi 207? - Vì trường hợp tiêu chuẩn nên dễ dàng và chuẩn. Trong khi các trường hợp đặc biệt có thể là ngoại lệ. Một khách hàng chỉ cần đọc cơ quan phản hồi và đưa ra các quyết định phức tạp hơn, nếu một tình huống đặc biệt đảm bảo điều đó.

Một tùy chọn sẽ là luôn trả về mã trạng thái 200 và sau đó trả về các lỗi cụ thể trong phần thân tài liệu JSON của bạn. Đây chính xác là cách một số API được thiết kế (chúng luôn trả về mã trạng thái 200 và gửi lỗi trong phần thân). Để biết thêm chi tiết về các cách tiếp cận khác nhau, hãy xem http://archive.oreilly.com/pub/post/restful_error_handling.html

Tôi nghĩ neilsimp1 là chính xác, nhưng tôi khuyên bạn nên thiết kế lại dữ liệu được gửi theo cách mà bạn có thể gửi 206 - Acceptedvà xử lý dữ liệu sau đó. Có lẽ với cuộc gọi lại.

Vấn đề với việc cố gắng gửi nhiều hành động trong một yêu cầu chính xác là thực tế là mỗi hành động nên có "trạng thái" riêng.

Nhìn vào việc nhập CSV (tôi không biết OP thực sự nói về cái gì nhưng nó là một phiên bản đơn giản). POST CSV và nhận lại 206. Sau đó, CSV có thể được nhập và bạn có thể nhận trạng thái nhập với GET (200) đối với URL hiển thị lỗi trên mỗi hàng.

POST /imports/ -> 206
GET  /imports/1 -> 200
GET  /imports/1/errors -> 200 -> Has a list of errors

Mô hình tương tự này có thể được áp dụng cho nhiều lần thay đổi hàng loạt

POST /operations/ -> 206
GET  /operations/1 -> 200
GET  /operations/1/errors -> 200 - > Has a list of errors.

Mã xử lý POST chỉ cần xác minh rằng định dạng của dữ liệu hoạt động là hợp lệ. Sau đó tại một thời điểm sau đó các hoạt động có thể được thực hiện. Trong một công nhân mặt đất, vì vậy bạn có thể mở rộng quy mô dễ dàng hơn, ví dụ. Sau đó, bạn có thể kiểm tra trạng thái của các hoạt động khi bạn muốn. Bạn có thể sử dụng bỏ phiếu hoặc gọi lại, hoặc luồng hoặc bất cứ điều gì để giải quyết nhu cầu cần biết khi một bộ hoạt động hoàn tất.

Đã có nhiều câu trả lời hay ở đây, nhưng thiếu một khía cạnh:

Hợp đồng mà khách hàng của bạn mong đợi là gì?

Mã trả về HTTP phải chỉ ra ít nhất một sự phân biệt thành công / thất bại và do đó đóng vai trò là "trường hợp ngoại lệ của người nghèo". Sau đó 200 có nghĩa là "hoàn thành hợp đồng" và 4xx hoặc 5xx cho thấy không hoàn thành.

Ngây thơ, tôi mong muốn hợp đồng yêu cầu nhiều hành động của bạn là "thực hiện tất cả các nhiệm vụ của tôi" và nếu một trong số chúng thất bại, thì yêu cầu đó đã không (hoàn toàn) thành công. Thông thường, với tư cách là một khách hàng, tôi hiểu 200 là "mọi thứ đều ổn" và các mã từ gia đình 400 và 500 buộc tôi phải suy nghĩ về hậu quả của một thất bại (một phần). Vì vậy, sử dụng 200 cho "tất cả các nhiệm vụ đã hoàn thành" và 500 cộng với phản hồi mô tả trong trường hợp thất bại một phần.

Một hợp đồng giả định khác có thể là "thử thực hiện tất cả các hành động". Sau đó, nó hoàn toàn phù hợp với hợp đồng nếu (một số) hành động thất bại. Vì vậy, bạn luôn trả lại 200 cộng với một tài liệu kết quả nơi bạn tìm thấy thông tin thành công / thất bại cho các nhiệm vụ riêng lẻ.

Vì vậy, những gì hợp đồng bạn muốn làm theo? Cả hai đều hợp lệ, nhưng cái đầu tiên (chỉ 200 trong trường hợp mọi thứ đã được thực hiện) đối với tôi trực quan hơn và phù hợp hơn với các mẫu phần mềm điển hình. Và đối với phần lớn các trường hợp dịch vụ đã hoàn thành tất cả các nhiệm vụ, khách hàng sẽ dễ dàng phát hiện ra trường hợp đó.

Một khía cạnh quan trọng cuối cùng: Làm thế nào để bạn truyền đạt quyết định hợp đồng của bạn với khách hàng của bạn? Ví dụ: trong Java, tôi sẽ sử dụng các tên phương thức như "do ALL ()" hoặc "tryToDoAll ()". Trong HTTP, bạn có thể đặt tên URL điểm cuối phù hợp, hy vọng rằng các nhà phát triển ứng dụng khách của bạn nhìn thấy, đọc và hiểu cách đặt tên (tôi sẽ không đặt cược vào điều đó). Thêm một lý do để chọn hợp đồng ít bất ngờ nhất.

Câu trả lời:

Chỉ cần sử dụng một yêu cầu cho mỗi hành động và chấp nhận thêm chi phí.

Mã trạng thái mô tả trạng thái của một thao tác. Do đó, nó có ý nghĩa để có một hoạt động cho mỗi yêu cầu.

Nhiều hoạt động độc lập phá vỡ hiệu trưởng mà mô hình phản hồi yêu cầu và mã trạng thái dựa trên. Bạn đang chiến đấu với bản chất.

HTTP / 1.1 và HTTP / 2 đã khiến chi phí yêu cầu HTTP thấp hơn nhiều. Tôi ước tính có rất ít tình huống mà các yêu cầu độc lập theo đợt được khuyến khích.

Mà nói,

(1) Bạn có thể thực hiện nhiều sửa đổi với yêu cầu PATCH ( RFC 5789 ). Tuy nhiên, điều này đòi hỏi những thay đổi không độc lập; chúng được áp dụng nguyên tử (tất cả hoặc không có gì).

(2) Những người khác đã chỉ ra mã Đa trạng thái 207. Tuy nhiên, điều này chỉ được xác định cho WebDAV ( RFC 4918 ), một phần mở rộng của HTTP.

Mã trạng thái 207 (Đa trạng thái) cung cấp trạng thái cho nhiều hoạt động độc lập (xem Phần 13 để biết thêm thông tin).

...

Phản hồi Đa trạng thái truyền tải thông tin về nhiều tài nguyên trong các tình huống có thể có nhiều mã trạng thái phù hợp. Phần tử [XML] gốc 'multistatus' giữ không hoặc nhiều phần tử 'phản hồi' theo bất kỳ thứ tự nào, mỗi phần tử có thông tin về một tài nguyên riêng lẻ.

Một phản hồi XML WebDAV 207 sẽ kỳ lạ như một con vịt trong API không phải là WebDAV. Đừng làm điều này.

Nếu bạn thực sự cần phải có nhiều hành động trong một yêu cầu, tại sao không bao gồm tất cả các hành động trong một giao dịch trong phần phụ trợ? Bằng cách đó, tất cả họ đều thành công hoặc tất cả đều thất bại.

Là một khách hàng sử dụng API, tôi có thể xử lý thành công hoặc thất bại hoàn toàn đối với lệnh gọi API. Thành công một phần là khó đối phó, vì tôi sẽ phải xử lý tất cả các trạng thái kết quả có thể.