API HTTP có nên luôn trả về phần thân không?

Có một số loại tiêu chuẩn liên quan đến phản hồi API HTTP không?

Sau khi đọc bài diễn văn này, tôi bắt đầu tự hỏi. Chúng tôi đang phát triển API HTTP JSON công khai trong công việc của mình và chúng tôi không trả lại bất cứ điều gì khi không thực sự cần thiết (ví dụ: PUT tới / resource / {id} chỉ trả về 200 khi OK hoặc mã 4XX hoặc 5XX tương ứng, nhưng không Cơ thể JSON)

Chúng ta có nên trả lại một cái chung chung {"success":true}như họ thảo luận về liên kết đó ở trên không, hoặc có thể trả lại phần thân "void" và xử lý mọi thứ với mã phản hồi http không?

Về PUT, nhưng cũng áp dụng cho POST. Các HTTP đặc điểm kỹ thuật phần 9 là một chút trống trên quy tắc hoặc tư vấn thậm chí (nên) khi nói đến kịch bản mà bạn đang mô tả. Dòng liên quan đến câu hỏi của bạn được bao phủ chặt chẽ nhất bởi:

Nếu tài nguyên mới được tạo, máy chủ gốc PHẢI thông báo cho tác nhân người dùng thông qua phản hồi 201 (Đã tạo). Nếu tài nguyên hiện có được sửa đổi, mã phản hồi 200 (OK) hoặc 204 (Không có nội dung) NÊN được gửi để cho biết hoàn thành yêu cầu thành công.

Tôi không nghĩ rằng tôi sẽ mất bất kỳ giấc ngủ nào vì nó, nhưng tôi sẽ hỏi, bạn sẽ đạt được gì khi thêm đoạn JSON vào phản hồi? Bạn vừa mới bỏ ra (OK, hàng loạt có thể là quá mức cần thiết!) Phản hồi lặp lại ít chính xác hơn những gì mã trạng thái nên đã nói với bạn. Nếu PUT của bạn dẫn đến một đối tượng mới trả về 201 (như ý định của PUT), nếu nó cập nhật một đối tượng trả về 204.

Ngẫu nhiên, API sang một bên, thay vì 200, nếu bạn không trả lại bất cứ điều gì, hãy sử dụng 204.

Giả sử rằng bạn đang phát triển một bộ giao diện RESTful, không có tiêu chuẩn nào, vì vậy dù bạn làm gì, hãy ghi chép lại, cung cấp các ví dụ và mọi thứ sẽ ổn.

Tiêu chuẩn HTTP cơ sở không bắt buộc phải có tài liệu được trả về cùng với phản hồi. Vì lợi ích kinh tế, khi một trạng thái HTTP chuyển tải tất cả những gì cần thiết, cơ thể sẽ lãng phí. Tuy nhiên, có các tiêu chuẩn được xây dựng dựa trên HTTP có thêm các quy tắc mới.

Có một tiêu chuẩn API JSON mở chỉ định:

• Một đối tượng JSON PHẢI nằm ở gốc của mọi tài liệu phản hồi API JSON . (chữ nghiêng thể hiện những gì tôi đã thêm để làm rõ văn bản)

Thật không may, tiêu chuẩn không chỉ định cách thể hiện một tài liệu trống và đó là một công việc đang được tiến hành. Tốt nhất tôi nên sử dụng nó như một hướng dẫn.

Một số ứng dụng (như ElasticSearch ) cung cấp api JSON đầy đủ và luôn có một số siêu dữ liệu để bạn có thể có ý tưởng tốt hơn về cách máy chủ quản lý dữ liệu của bạn. Đối tượng phản hồi tiêu chuẩn cho bạn biết về tình trạng của chỉ mục, nếu yêu cầu dẫn đến lỗi, có bao nhiêu nút bị ảnh hưởng, v.v. tiêu chuẩn jsonapi.org.

JQuery và các khung Javascript tương tự cho rằng sẽ luôn có một tài liệu. Câu hỏi là bạn muốn kiểm tra lỗi bao nhiêu đối với người tiêu dùng API? Nếu bạn đưa ra một định dạng chuẩn cho tất cả các phản hồi chỉ được mở rộng dựa trên loại yêu cầu, bạn đáp ứng nhu cầu về một tài liệu trả lại và có thể tạo điều kiện dễ dàng hơn cho người tiêu dùng API của bạn gỡ lỗi.

Không có ví dụ, đối với 204 phản hồi, chúng tôi không được bao gồm nội dung thư. {thành công | trạng thái | isSuccessful: true} là dự phòng.

Trong thực tế (hoặc tôi nên nói trong phiên bản sau của jquery), phản hồi trống cho loại nội dung ứng dụng / json làm tăng lỗi. Tôi hiểu được lập luận rằng vì đó là ứng dụng / json nên nó phải có phần thân json hợp lệ. Vì vậy, phản hồi trống cho loại nội dung ứng dụng / json sẽ là 'null' hoặc '{}' là json hợp lệ.

Có một cách khác nên hoạt động cho jquery, đó là không trả lại ứng dụng / json cho các phản hồi trống. Chỉ cần sử dụng văn bản / thuần túy hoặc một cái gì đó và đảm bảo khách hàng có thể xử lý loại đó.

Lưu ý tôi chỉ có thể nhớ 204 vì rõ ràng cấm trả lại nội dung thư. Những gì chúng tôi tìm thấy là chúng tôi không thể luôn sử dụng 204. Vấn đề là tiêu đề phản hồi thả MSIE cho 204 phản hồi, vì vậy không có nội dung và tiêu đề, điều này rất tệ. Vì nhiều người đang sử dụng MSIE, chúng tôi đã phải thay đổi nó thành 200 trạng thái.

Không nhưng nó sẽ giúp cho tính nhất quán của mã của bạn. Nó cũng tốt cho mục đích gỡ lỗi. Nó cũng sẽ giúp đỡ rất nhiều trong việc duy trì trang web. Hãy nhớ điều này: Mã lỗi dành cho máy, Thông báo lỗi dành cho con người. Vì vậy, tôi đề nghị cho bạn sử dụng một cơ thể phản ứng. Dù sao, hiệu ứng tiêu cực của nó chỉ là tối thiểu (chỉ một vài byte được gửi qua mạng) so với lợi ích của nó. Một điều nữa, nó cũng sẽ giúp bạn không quên viết một nội dung tin nhắn khi cần thiết.

Tôi sẽ không trả lại trạng thái thành công đơn giản trong phản hồi, mã lỗi http chỉ báo hiệu thành công hoặc lỗi. Tôi chỉ bao gồm sử dụng chính phản hồi để thêm thông tin lỗi chi tiết, chẳng hạn như mã lỗi cụ thể của ứng dụng hoặc thông báo lỗi.

Đối với các yêu cầu PUT, PATCH và POST, bạn thường trả về trạng thái trả về trạng thái của tài nguyên sau khi yêu cầu được áp dụng, không phải là phản hồi trống.

Đối với các yêu cầu POST đại diện cho một hành động thay vì chỉ đơn giản là tạo một tài nguyên (không phải là RESTful, nhưng vẫn hữu ích trong thực tế), không có dữ liệu hữu ích để trả về, tôi sẽ trả về một phản hồi bao gồm một đối tượng json trống, tức là {}. Bằng cách đó, khách hàng nhận được phản hồi hợp lệ và thêm một số thông tin sau này không có khả năng phá vỡ nó.

Đối với các yêu cầu XÓA trả về 204 và một phần thân trống là khá phổ biến, điều này có ý nghĩa vì tài nguyên không tồn tại sau đó.

Tôi sẽ đề nghị chỉ trả lại những gì cần thiết + làm rõ một chút.

Ví dụ: tùy thuộc vào cách sử dụng API của bạn, bạn có thể bao gồm một bản sao của đối tượng, như tồn tại sau khi được lưu.

Vì vậy, POST của {key: 123} có thể trả về {key: 123, foo: 'bar'}.

Ý tưởng cơ bản là tốt hơn là trả lại đối tượng sau đó phải truy vấn lại nó.

Điều đó nói rằng, người tiêu dùng API của bạn không cần đối tượng, không cần phải trả lại.

Tôi thường trả về {thành công: true} hoặc một số thứ tương tự, khi không có đối tượng nào được yêu cầu trên POST PUT và PATCH vì nó giúp cho việc kết thúc nhận được dễ dàng hơn. Điều đó nói rằng, tốt hơn 99% thời gian để trả lại đại diện đã lưu của đối tượng, hiếm khi nào họ sẽ không cần đến nó và "rẻ hơn" để gửi tất cả trong một yêu cầu sau đó thành hai.

Cụ thể, trong phòng thí nghiệm, hoàn toàn có thể xử lý mọi thứ chỉ bằng mã trạng thái, trong thế giới thực, tốt hơn là trả lại một số dữ liệu, ngay cả khi dư thừa, để người tiêu dùng API có thể dễ dàng hiểu được những gì bạn đang cố gắng nói.

Trả về 200 {thành công: true} cho phép mọi người viết mã theo cả hai cách:

if response.code == 200
  do stuff
end

và

if response.body.success
  do stuff
end

ngoài ra nó không khó để làm về phía bạn.

Cuối cùng, (xin lỗi về cấu trúc câu trả lời của poos), bằng cách cung cấp một api JSON công khai, bạn sẽ từ bỏ rất nhiều quyền kiểm soát về cách sử dụng nó. Một số khách hàng có thể phản ứng khác nhau với các cơ quan khác nhau (hoặc thiếu ở đó) hoặc mã trạng thái.