Các tiêu chuẩn hoặc thực tiễn tốt nhất có tồn tại để cấu trúc các phản hồi JSON từ API không? Rõ ràng, dữ liệu của mỗi ứng dụng là khác nhau, do đó tôi không quan tâm lắm, mà là "bản tóm tắt phản hồi", nếu bạn muốn. Một ví dụ về những gì tôi muốn nói:

Yêu cầu thành công:

{
  "success": true,
  "payload": {
    /* Application-specific data would go here. */
  }
}

Yêu cầu thất bại:

{
  "success": false,
  "payload": {
    /* Application-specific data would go here. */
  },
  "error": {
    "code": 123,
    "message": "An error occurred!"
  }
}

Vâng, có một vài tiêu chuẩn (mặc dù một số quyền tự do theo định nghĩa của tiêu chuẩn) đã xuất hiện:

1. API JSON - API JSON cũng bao gồm việc tạo và cập nhật tài nguyên, không chỉ phản hồi.
2. JSend - Đơn giản và có lẽ là những gì bạn đang làm.
3. Giao thức JSON OData - Rất phức tạp.
4. HAL - Thích OData nhưng nhắm đến HATEOAS thích.

Ngoài ra còn có các định dạng mô tả API JSON:

• Đi vênh vang
  • Lược đồ JSON (được sử dụng bởi vênh vang nhưng bạn có thể sử dụng độc lập)
• WADL trong JSON
• RAML
• HAL vì HATEOAS trong lý thuyết là tự mô tả.

Hướng dẫn Google JSON

Trả lời thành công data

{
  "data": {
    "id": 1001,
    "name": "Wing"
  }
}

Trả lời lỗi error

{
  "error": {
    "code": 404,
    "message": "ID not found"
  }
}

và nếu khách hàng của bạn là JS, bạn có thể sử dụng if ("error" in response) {}để kiểm tra xem có lỗi không.

Tôi đoán một tiêu chuẩn defacto chưa thực sự xuất hiện (và có thể không bao giờ). Nhưng bất kể, đây là mất của tôi:

Yêu cầu thành công:

{
  "status": "success",
  "data": {
    /* Application-specific data would go here. */
  },
  "message": null /* Or optional success message */
}

Yêu cầu thất bại:

{
  "status": "error",
  "data": null, /* or optional error payload */
  "message": "Error xyz has occurred"
}

Ưu điểm: Các yếu tố cấp cao nhất giống nhau trong cả trường hợp thành công và lỗi

Nhược điểm: Không có mã lỗi, nhưng nếu bạn muốn, bạn có thể thay đổi trạng thái thành mã (thành công hay thất bại), hoặc - bạn có thể thêm một mục cấp cao nhất khác có tên là "mã".

Giả sử câu hỏi của bạn là về thiết kế dịch vụ web REST và chính xác hơn là liên quan đến thành công / lỗi.

Tôi nghĩ có 3 loại thiết kế khác nhau.

1. Chỉ sử dụng mã Trạng thái HTTP để cho biết nếu có lỗi và cố gắng giới hạn bản thân ở các tiêu chuẩn (thường là đủ).

   • Ưu điểm: Nó là một tiêu chuẩn độc lập với api của bạn.
   • Nhược điểm: Ít thông tin về những gì thực sự đã xảy ra.

2. Sử dụng HTTP Status + json body (ngay cả khi đó là lỗi). Xác định cấu trúc thống nhất cho các lỗi (ví dụ: mã, thông báo, lý do, loại, v.v.) và sử dụng nó cho các lỗi, nếu thành công thì chỉ cần trả về phản hồi json dự kiến.

   • Ưu điểm: Vẫn là tiêu chuẩn khi bạn sử dụng mã trạng thái HTTP hiện có và bạn trả về một json mô tả lỗi (bạn cung cấp thêm thông tin về những gì đã xảy ra).
   • Nhược điểm: json đầu ra sẽ thay đổi tùy theo nếu đó là lỗi hay thành công.

3. Quên trạng thái http (ví dụ: luôn là trạng thái 200), luôn sử dụng json và thêm vào thư mục gốc của phản hồi boolean và một đối tượng lỗi (mã, thông báo, v.v.) sẽ được đưa ra nếu đó là lỗi nếu không các trường khác (thành công) được dân cư.

   • Ưu điểm: Máy khách chỉ xử lý phần thân của phản hồi là chuỗi json và bỏ qua trạng thái (?).

   • Nhược điểm: Tiêu chuẩn ít hơn.

Tùy bạn chọn :)

Tùy thuộc vào API, tôi sẽ chọn 2 hoặc 3 (tôi thích 2 cho json rest apis). Một điều khác tôi đã có kinh nghiệm trong việc thiết kế REST Api là tầm quan trọng của tài liệu cho từng tài nguyên (url): các tham số, phần thân, phản hồi, các tiêu đề, v.v.

Tôi cũng khuyên bạn nên sử dụng jersey (triển khai jax -rs) + genson (thư viện dữ liệu java / json). Bạn chỉ phải thả genson + jersey trong classpath của bạn và json được tự động hỗ trợ.

BIÊN TẬP:

• Giải pháp 2 là khó thực hiện nhất nhưng ưu điểm là bạn có thể xử lý các trường hợp ngoại lệ một cách độc đáo và không chỉ các lỗi kinh doanh, nỗ lực ban đầu quan trọng hơn nhưng bạn sẽ giành chiến thắng trong dài hạn.

• Giải pháp 3 là dễ thực hiện trên cả hai mặt, máy chủ và máy khách nhưng nó không đẹp lắm vì bạn sẽ phải gói gọn các đối tượng bạn muốn trả về trong một đối tượng phản hồi có chứa lỗi answerValid +.

Các RFC 7807: Vấn đề chi tiết cho HTTP API là vào lúc này là điều gần nhất chúng ta phải là một tiêu chuẩn chính thức.

Sau đây là định dạng json instagram đang sử dụng

{
    "meta": {
         "error_type": "OAuthException",
         "code": 400,
         "error_message": "..."
    }
    "data": {
         ...
    },
    "pagination": {
         "next_url": "...",
         "next_max_id": "13872296"
    }
}

Tôi sẽ không kiêu ngạo khi tuyên bố rằng đây là một tiêu chuẩn nên tôi sẽ sử dụng mẫu "Tôi thích".

Tôi thích phản hồi ngắn gọn hơn (khi yêu cầu một danh sách / bài viết tôi muốn một mảng bài viết JSON).

Trong các thiết kế của tôi, tôi sử dụng HTTP cho báo cáo trạng thái, 200 chỉ trả về tải trọng.

400 trả về một thông báo về những gì sai với yêu cầu:

{"message" : "Missing parameter: 'param'"}

Trả về 404 nếu mô hình / trình điều khiển / URI không tồn tại

Nếu có lỗi khi xử lý về phía tôi, tôi trả về 501 với một thông báo:

{"message" : "Could not connect to data store."}

Từ những gì tôi đã thấy khá nhiều khung REST-ish có xu hướng nằm dọc theo các dòng này.

Cơ sở lý luận :

JSON được coi là một định dạng tải trọng , nó không phải là một giao thức phiên. Toàn bộ ý tưởng về tải trọng phiên phiên dài đến từ thế giới XML / SOAP và các lựa chọn sai lầm khác nhau đã tạo ra các thiết kế cồng kềnh đó. Sau khi chúng tôi nhận ra tất cả điều đó là một vấn đề đau đầu, toàn bộ quan điểm của REST / JSON là KIẾM nó và tuân thủ HTTP. Tôi không nghĩ rằng có bất kỳ tiêu chuẩn từ xa nào trong cả JSend và đặc biệt là không có nhiều chi tiết hơn trong số đó. XHR sẽ phản ứng với phản hồi HTTP, nếu bạn sử dụng jQuery cho AJAX của mình (giống như hầu hết), bạn có thể sử dụng try/ catchvà done()/ fail()gọi lại để ghi lại lỗi. Tôi không thể thấy cách đóng gói các báo cáo trạng thái trong JSON hữu ích hơn thế.

Đối với những gì nó có giá trị tôi làm điều này khác nhau. Một cuộc gọi thành công chỉ có các đối tượng JSON. Tôi không cần một đối tượng JSON cấp cao hơn có chứa trường thành công cho biết trường thực và trường tải có đối tượng JSON. Tôi chỉ trả về đối tượng JSON thích hợp với 200 hoặc bất cứ điều gì phù hợp trong phạm vi 200 cho trạng thái HTTP trong tiêu đề.

Tuy nhiên, nếu có lỗi (một cái gì đó trong họ 400), tôi trả về một đối tượng lỗi JSON được định dạng tốt. Ví dụ: nếu khách hàng đang ĐĂNG người dùng có địa chỉ email và số điện thoại và một trong số đó không đúng định dạng (nghĩa là tôi không thể chèn nó vào cơ sở dữ liệu cơ bản của mình), tôi sẽ trả lại một cái gì đó như sau:

{
  "description" : "Validation Failed"
  "errors" : [ {
    "field" : "phoneNumber",
    "message" : "Invalid phone number."
  } ],
}

Các bit quan trọng ở đây là thuộc tính "trường" phải khớp chính xác với trường JSON không thể xác thực. Điều này cho phép khách hàng biết chính xác những gì đã sai với yêu cầu của họ. Ngoài ra, "tin nhắn" nằm trong miền địa phương của yêu cầu. Nếu cả "emailAddress" và "phoneNumber" đều không hợp lệ thì mảng "lỗi" sẽ chứa các mục nhập cho cả hai. Phần thân phản hồi JSON 409 (Xung đột) có thể trông như thế này:

{
  "description" : "Already Exists"
  "errors" : [ {
    "field" : "phoneNumber",
    "message" : "Phone number already exists for another user."
  } ],
}

Với mã trạng thái HTTP và JSON này, máy khách có tất cả những gì họ cần để phản hồi lỗi theo cách xác định và nó không tạo ra một tiêu chuẩn lỗi mới cố gắng hoàn thành thay thế mã trạng thái HTTP. Lưu ý, những điều này chỉ xảy ra trong phạm vi 400 lỗi. Đối với bất cứ điều gì trong phạm vi 200 tôi chỉ có thể trả lại bất cứ điều gì là phù hợp. Đối với tôi nó thường là một đối tượng JSON giống HAL nhưng điều đó không thực sự quan trọng ở đây.

Một điều tôi nghĩ về việc thêm là một mã lỗi số trong các mục mảng "lỗi" hoặc gốc của chính đối tượng JSON. Nhưng cho đến nay chúng tôi không cần nó.

Họ không đồng ý về các định dạng phản hồi api còn lại của các đại gia phần mềm lớn - Google, Facebook, Twitter, Amazon và những người khác, mặc dù nhiều liên kết đã được cung cấp trong các câu trả lời ở trên, trong đó một số người đã cố gắng chuẩn hóa định dạng phản hồi.

Do nhu cầu của API có thể khác nhau, rất khó để đưa mọi người lên tàu và đồng ý với một số định dạng. Nếu bạn có hàng triệu người dùng sử dụng API của mình, tại sao bạn lại thay đổi định dạng phản hồi của mình?

Sau đây là nhận định của tôi về định dạng phản hồi được lấy cảm hứng từ Google, Twitter, Amazon và một số bài đăng trên internet:

https://github.com/adnan-kamili/rest-api-response-format

Tập tin vênh vang:

https://github.com/adnan-kamili/swagger-sample-template

Điểm của JSON là nó hoàn toàn năng động và linh hoạt. Bẻ cong nó thành bất cứ điều gì bạn muốn, bởi vì nó chỉ là một tập hợp các đối tượng và mảng JavaScript được tuần tự hóa, bắt nguồn từ một nút duy nhất.

Loại rootnode là tùy thuộc vào bạn, nó chứa gì tùy thuộc vào bạn, bạn có gửi siêu dữ liệu cùng với phản hồi hay không, tùy thuộc vào việc bạn đặt loại mime thành application/jsonhay để nó tùy text/plainthuộc vào bạn ( miễn là bạn biết cách xử lý các trường hợp cạnh).

Xây dựng một lược đồ nhẹ mà bạn thích.
Cá nhân, tôi đã thấy rằng phục vụ theo dõi phân tích và phục vụ mp3 / ogg và thư viện hình ảnh và nhắn tin văn bản và các gói mạng để chơi trò chơi trực tuyến, và các bài đăng trên blog và nhận xét blog đều có những yêu cầu rất khác nhau về những gì gửi và những gì nhận được và làm thế nào chúng nên được tiêu thụ.

Vì vậy, điều cuối cùng tôi muốn, khi làm tất cả những điều đó, là cố gắng làm cho mỗi cái phù hợp với cùng một tiêu chuẩn soạn sẵn, dựa trên XML2.0 hoặc somesuch.

Điều đó nói rằng, có rất nhiều điều để nói về việc sử dụng các lược đồ có ý nghĩa với bạn và được suy nghĩ kỹ.
Chỉ cần đọc một số phản hồi API, lưu ý những gì bạn thích, chỉ trích những gì bạn không, viết những lời chỉ trích đó và hiểu lý do tại sao họ chà xát sai cách và sau đó suy nghĩ về cách áp dụng những gì bạn đã học vào những gì bạn cần.

JSON-RPC 2.0 định nghĩa một định dạng yêu cầu và phản hồi tiêu chuẩn và là một luồng gió mới sau khi làm việc với các API REST.

Đối với những người đến sau, ngoài câu trả lời được chấp nhận bao gồm API HAL, JSend và JSON, tôi sẽ thêm một vài thông số kỹ thuật khác đáng để xem xét:

• JSON-LD , là Khuyến nghị của W3C và chỉ định cách xây dựng các Dịch vụ web có thể tương tác trong JSON
• Loại Hypermedia dành cho REST, tự nhận là "loại hypermedia dựa trên JSON đơn giản và trực quan cho REST"

Khung cơ bản được đề xuất có vẻ ổn, nhưng đối tượng lỗi như được định nghĩa là quá hạn chế. Người ta thường không thể sử dụng một giá trị duy nhất để diễn đạt vấn đề, và thay vào đó là một chuỗi các vấn đề và nguyên nhân là cần thiết .

Tôi đã làm một nghiên cứu nhỏ và thấy rằng định dạng phổ biến nhất để trả về lỗi (ngoại lệ) là một cấu trúc của hình thức này:

{
   "success": false,
   "error": {
      "code": "400",
      "message": "main error message here",
      "target": "approx what the error came from",
      "details": [
         {
            "code": "23-098a",
            "message": "Disk drive has frozen up again.  It needs to be replaced",
            "target": "not sure what the target is"
         }
      ],
      "innererror": {
         "trace": [ ... ],
         "context": [ ... ]
      }
   }
}

Đây là định dạng được đề xuất bởi tiêu chuẩn dữ liệu OASIS OASIS OData và dường như là tùy chọn tiêu chuẩn nhất hiện có, tuy nhiên dường như không có tỷ lệ chấp nhận cao của bất kỳ tiêu chuẩn nào tại thời điểm này. Định dạng này phù hợp với đặc tả JSON-RPC.

Bạn có thể tìm thấy thư viện mã nguồn mở hoàn chỉnh thực hiện điều này tại: Mendocino JSON Utility . Thư viện này hỗ trợ các Đối tượng JSON cũng như các ngoại lệ.

Các chi tiết được thảo luận trong bài đăng trên blog của tôi về Xử lý lỗi trong API JSON REST

Không có vi phạm pháp luật hoặc tiêu chuẩn ngoài vòng pháp luật ngoài ý nghĩa thông thường. Nếu chúng ta trừu tượng điều này giống như hai người nói chuyện, tiêu chuẩn là cách tốt nhất để họ có thể hiểu chính xác lẫn nhau bằng những từ tối thiểu trong thời gian tối thiểu. Trong trường hợp của chúng tôi, 'từ tối thiểu' là tối ưu hóa băng thông cho hiệu quả vận chuyển và 'hiểu chính xác' là cấu trúc cho hiệu quả của trình phân tích cú pháp; mà cuối cùng kết thúc với dữ liệu càng ít và cấu trúc chung; để nó có thể đi qua một lỗ pin và có thể được phân tích cú pháp thông qua một phạm vi chung (ít nhất là ban đầu).

Hầu như trong mọi trường hợp được đề xuất, tôi thấy các phản hồi riêng biệt cho kịch bản 'Thành công' và 'Lỗi', đây là loại mơ hồ đối với tôi. Nếu hai câu trả lời khác nhau trong hai trường hợp này, thì tại sao chúng ta thực sự cần đặt cờ 'Thành công' ở đó? Không rõ ràng rằng sự vắng mặt của 'Lỗi' là 'Thành công'? Có thể có phản hồi trong đó 'Thành công' là TRUE với bộ 'Lỗi' không? Hoặc theo cách, 'Thành công' là SAI không có 'Lỗi' được đặt? Chỉ một lá cờ là không đủ? Tôi chỉ muốn có cờ 'Lỗi', vì tôi tin rằng sẽ có ít 'Lỗi' hơn 'Thành công'.

Ngoài ra, chúng ta có nên thực sự biến 'Lỗi' thành cờ không? Nếu tôi muốn phản hồi với nhiều lỗi xác nhận thì sao? Vì vậy, tôi thấy hiệu quả hơn khi có nút 'Lỗi' với mỗi lỗi là con của nút đó; trong đó một nút trống (được tính bằng 0) sẽ báo hiệu 'Thành công'.

Phản hồi tốt nhất cho apis web có thể dễ dàng hiểu được bởi các nhà phát triển di động.

Đây là phản hồi "Thành công"

{  
   "ReturnCode":"1",
   "ReturnMsg":"Successfull Transaction",
   "ReturnValue":"",
   "Data":{  
      "EmployeeName":"Admin",
      "EmployeeID":1
   }
}

Đây là phản hồi "Lỗi"

{
    "ReturnCode": "4",
    "ReturnMsg": "Invalid Username and Password",
    "ReturnValue": "",
    "Data": {}
}