Cấu trúc trả về mã lỗi REST API

Question

Tôi đang viết một API REST và tôi đã tình cờ gặp một vấn đề. Cách tốt nhất để trả lại các lỗi xác thực là gì.

Cho đến bây giờ tôi đã trả lại thông báo lỗi đổ vào một mã lỗi chung (giả sử yêu cầu xấu ví dụ)

{ 
    "status": 400, 
    "error": { 
     "code": 1, // General bad request code 
     "message": [ 
       "The Key \"a\" is missing", 
       "The Key \"b\" is missing", 
       "The Key \"c\" is missing", 
       "Incorrect Format for field \"y\"" 
     ] 
    } 

) 

Tôi đã nghiên cứu thêm một chút về cách nên một phản ứng API tốt nên trông giống như và tôi nghĩ các tùy chọn sau:

1. Dừng tại các lỗi gặp phải đầu tiên và trả về một phản ứng với mã lỗi cụ thể

   { 
       "status": 400, //Same as the HTTP header returned 
       "error" { 
        "code": 1, // Specific field validation error code 
        "message": "Field \"x\" is missing from the array structure", 
        "developer_message": "The request structure must contain the following fields {a,b,c{x,y,z}}", 
        "more_info" => "www.api.com/help/errors/1" 
       } 
   ) 
   

2. Phân tích cú pháp tất cả dữ liệu yêu cầu và trả về nhiều lỗi xác thực trường.

   { 
       "status": 400, 
       "error": { 
       "code": 1 //General bad Request code 
       "message": "Bad Request", 
       "developer_message": "Field validation errors." 
       "more_info": "www.api.com/help/errors/1", 
       "error_details": { 
         0: { 
           "code": 2 // Specific field validation error code 
           "message": "Field \"x\" is missing from the array structure", 
           "developer_message": "The request structure must contain the following fields {a,b,c{x,y,z}}", 
           "more_info": "www.api.com/help/errors/2" 
          }, 
   
         1: { 
           "code": 3 // Specific field validation error code 
           "message": "Incorrect Format for field \"y\"", 
           "developer_message": "The field \"y\" must be in the form of \"Y-m-d\"", 
           "more_info": "www.api.com/help/errors/3" 
          } 
           } 
        } 
       } 
   

Trong tùy chọn quan điểm của tôi 2 sẽ là đúng cách (nó cung cấp thông tin hữu ích hơn cho các nhà phát triển/người dùng cuối và tải máy chủ có thể thấp hơn (ít yêu cầu/không cần phải hợp lệ lại dữ liệu hợp lệ/không cần tính toán chữ ký và xác thực người dùng)), nhưng tôi đang lang thang thực hành tốt nhất là gì và nếu có cách khác để xử lý loại vấn đề này.

Ngoài ra tôi nghĩ phương án 1 vẫn còn hợp lệ nếu tôi nhận được một lỗi nghiêm trọng duy nhất trong dòng chảy của kịch bản. (Không lỗi xác nhận)

Xin lưu ý rằng mã chỉ là một mảng đơn giản chỉ cần như vậy sẽ dễ dàng hơn để làm theo. Định dạng phản hồi sẽ là JSON hoặc XML.

Answer 1

Cá nhân tôi sẽ cung cấp cho người dùng ít chi tiết hơn và đổ lỗi cần thiết cho nhà phát triển trong bảng nhật ký cơ sở dữ liệu hoặc nhật ký hệ thống. Do thực tế bạn đang sử dụng JSON và phổ biến nhất trên các máy chủ Apache và mã của bạn có vẻ là php (nhưng ví dụ mã của bạn với các dấu ngoặc nhọn có thể là một số ngôn ngữ có nguồn gốc từ PASCAL ví dụ: C, C# PERL, PHP, CSharp). Đây là cách để đưa các lỗi tùy chỉnh đầu ra vào nhật ký hệ thống nếu bạn chưa biết làm thế nào trong php http://php.net/manual/en/function.syslog.php. Nếu bạn đang sử dụng một cấu hình hiếm hơn IIS với JSON và CSharp thì các thư viện .NET cũng tương tự. Nếu bạn cung cấp cho người dùng của mình quá nhiều thông tin khi xảy ra lỗi, bạn cũng đang cung cấp cho một hacker trong tương lai một cách để thăm dò trang web của bạn.

Answer 2

Tôi đã sử dụng # 2 bản thân mình một vài lần. Nó tốt hơn # 1? Tôi nghĩ rằng phụ thuộc vào những gì API của bạn đang được sử dụng cho.

Tôi thích # 2 vì nó cung cấp cho nhà phát triển đang thử nghiệm API với một số cuộc gọi thử nghiệm tổng quan nhanh về tất cả lỗi/sai lầm mà anh ta đưa ra trong yêu cầu, nên anh ấy biết ngay lỗi/lỗi nào anh ấy phải sửa yêu cầu đó hợp lệ. Nếu bạn trả lại từng lỗi một (như trong # 1), bạn phải tiếp tục thử lại yêu cầu và các ngón tay chéo với hy vọng nó sẽ hợp lệ trong lần này.

Nhưng như tôi đã nói # 2 rất hữu ích cho nhà phát triển, nhưng lý do không thực sự áp dụng cho người dùng cuối. Người dùng cuối thường không quan tâm nó được triển khai như thế nào. Liệu phần mềm có đang thực hiện 1 yêu cầu trả về 5 lỗi hoặc 5 yêu cầu tiếp theo trả về 1 lỗi.
Miễn là nó được xử lý tốt trong ứng dụng khách, người dùng cuối sẽ không nhận thấy sự khác biệt. Làm thế nào để xử lý mà tất nhiên rất nhiều phụ thuộc vào những gì khách hàng thực sự là.

Tiếp theo để đẩy nhanh quá trình phát triển, lợi ích khác của # 2 (trong sản xuất) là yêu cầu ít yêu cầu hơn, điều này làm giảm tải máy chủ.

---

I would like to know if anyone went #2 and maybe have any improvements on it so I opened a bounty.

Chắc chắn có những cải tiến được thực hiện. Vì nó là, có một số dữ liệu trong cơ thể có thể được bỏ qua.

{ 
    "status": 400, 
    "error": { 
    "code": 1 //General bad Request code 
    "message": "Bad Request", 
    "developer_message": "Field validation errors." 
    "more_info": "www.api.com/help/errors/1", 
    "error_details": { 
      0: { 
        "code": 2 // Specific field validation error code 
        "message": "Field \"x\" is missing from the array structure", 
        "developer_message": "The request structure must contain the following fields {a,b,c{x,y,z}}", 
        "more_info": "www.api.com/help/errors/2" 
       }, 

      1: { 
       (
        "code": 3 // Specific field validation error code 
        "message": "Incorrect Format for field \"y\"", 
        "developer_message": "The field \"y\" must be in the form of \"Y-m-d\"", 
        "more_info": "www.api.com/help/errors/3" 
       ) 
      } 
) 

Với phản hồi HTTP, mã trạng thái không được đưa vào phần nội dung, nhưng trong tiêu đề. Điều này có nghĩa là bạn có thể bỏ qua "status": 400 và "message": "Bad Request" tại đây. 400 phải là mã trạng thái của phản hồi và 400 có nghĩa là Yêu cầu không hợp lệ. Đó là một tiêu chuẩn HTTP và không cần phải được giải thích trong phản hồi. Ngoài ra "developer_message": "Field validation errors." là loại trùng lặp, vì các lỗi cụ thể đã được bao gồm trong từng lỗi riêng biệt, vì vậy chúng tôi có thể bỏ điều đó ra.

Điều này khiến

{ 
    "error": { 
    "code": 1 //General bad Request code 
    "more_info": "www.api.com/help/errors/1", 
    "error_details": { 
      0: { 
        "code": 2 // Specific field validation error code 
        "message": "Field \"x\" is missing from the array structure", 
        "developer_message": "The request structure must contain the following fields {a,b,c{x,y,z}}", 
        "more_info": "www.api.com/help/errors/2" 
       }, 

      1: { 
       (
        "code": 3 // Specific field validation error code 
        "message": "Incorrect Format for field \"y\"", 
        "developer_message": "The field \"y\" must be in the form of \"Y-m-d\"", 
        "more_info": "www.api.com/help/errors/3" 
       ) 
      } 
) 

---

"code": 1 //General bad Request code 
"more_info": "www.api.com/help/errors/1", 

Những 2 dòng không thực sự có ý nghĩa nữa bây giờ. Họ cũng không bắt buộc, vì mỗi lỗi có nó là mã và thông tin riêng liên kết, vì vậy chúng tôi có thể dải những dòng này là tốt, để lại

{ 
    "error": { 
    "error_details": { 
      0: { 
        "code": 2 // Specific field validation error code 
        "message": "Field \"x\" is missing from the array structure", 
        "developer_message": "The request structure must contain the following fields {a,b,c{x,y,z}}", 
        "more_info": "www.api.com/help/errors/2" 
       }, 

      1: { 
       (
        "code": 3 // Specific field validation error code 
        "message": "Incorrect Format for field \"y\"", 
        "developer_message": "The field \"y\" must be in the form of \"Y-m-d\"", 
        "more_info": "www.api.com/help/errors/3" 
       ) 
      } 
) 

Mã 400 tình trạng này đã chỉ ra có một lỗi, vì vậy bạn don' t phải chỉ ra "error": {error details} nữa, bởi vì chúng tôi đã biết có lỗi. Danh sách lỗi có thể chỉ đơn giản là trở thành đối tượng gốc:

[ 
    { 
     "code": 2//Specificfieldvalidationerrorcode 
     "message": "Field \"x\" is missing from the array structure", 
     "developer_message": "The request structure must contain the following fields {a,b,c{x,y,z}}", 
     "more_info": "www.api.com/help/errors/2" 
    }, 
    { 
     "code": 3//Specificfieldvalidationerrorcode 
     "message": "Incorrect Format for field \"y\"", 
     "developer_message": "The field \"y\" must be in the form of \"Y-m-d\"", 
     "more_info": "www.api.com/help/errors/3" 
    } 
] 

Vì vậy, tất cả những gì còn lại trong cơ thể giờ đây chỉ đơn giản là danh sách lỗi.

Mã trạng thái được chỉ định trong tiêu đề phản hồi.
Chi tiết được chỉ định trong phần phản hồi.

Answer 3

Trước hết, bạn đã cung cấp tài liệu về các phương pháp Rest API cho khách hàng. Vì vậy, dự kiến ​​từ khách hàng/nhà phát triển để cung cấp dữ liệu hợp lệ cho các tham số.

Hiện đã nói rằng # 1 là cách tốt nhất để thực hiện API Rest. Trách nhiệm của nhà phát triển là giảm mức sử dụng máy chủ ở mức tối đa có thể. Vì vậy, nếu bạn gặp bất kỳ lỗi nghiêm trọng nào, hãy tạo một phản hồi với mã lỗi tương ứng và thông báo lỗi và trả về nó.

Hơn nữa, chúng tôi không thể chắc chắn rằng có nhiều lỗi hơn sau khi chúng tôi gặp phải. Vì vậy, không có điểm phân tích phần còn lại của dữ liệu. Nó sẽ không hoạt động tốt trong trường hợp xấu nhất.

Answer 4

Hãy xem Facebook's Graph API. Điều đó rất khó và rất nhiều lỗi được tạo ra nhiều nhất. Đây là những gì Facebook trả về một lỗi API:

{ 
    "error": { 
    "message": "Message describing the error", 
    "type": "OAuthException", 
    "code": 190, 
    "error_subcode": 460, 
    "error_user_title": "A title", 
    "error_user_msg": "A message" 
    } 
} 

Họ cố gắng làm cho các API đồ hữu ích như có thể, nhưng họ dường như trở về một lỗi cụ thể với một mã số và subcode (Ref). Thực tế là mỗi lỗi có mã riêng của nó có nghĩa là việc tìm kiếm mã hoặc thông báo nói trên trở nên dễ dàng hơn làm điểm bắt đầu để gỡ lỗi.Đó có thể là lý do tại sao họ không tích lũy thông báo lỗi trong phản hồi lỗi chính thức của họ. Nếu nó đủ tốt và thuận tiện cho Facebook, nó có thể đủ tốt cho chúng tôi.

phản ứng lỗi mẫu:

{ 
    "error": { 
    "message": "(#200) Must have a valid access_token to access this endpoint", 
    "type": "OAuthException", 
    "code": 200 
    } 
} 

và

"error": { 
    "message": "(#604) Your statement is not indexable. The WHERE clause must contain 
    an indexable column. Such columns are marked with * in the tables linked from 
    http://developers.facebook.com/docs/reference/fql ", 
    "type": "OAuthException", 
    "code": 604 
} 

---

Tiếp theo là JSend mà "là một đặc điểm kỹ thuật mà đưa ra một số quy tắc cho JSON phản ứng như thế nào từ các máy chủ web nên được định dạng. " Mục tiêu của họ là:

There are lots of web services out there providing JSON data, and each has its own way of formatting responses. Also, developers writing for JavaScript front-ends continually re-invent the wheel on communicating data from their servers. While there are many common patterns for structuring this data, there is no consistency in things like naming or types of responses. Also, this helps promote happiness and unity between backend developers and frontend designers, as everyone can come to expect a common approach to interacting with one another.

Đây là một thông báo lỗi mẫu:

{ 
    "status" : "fail", 
    "data" : { "title" : "A title is required" } 
} 

Dường như Facebook và nhóm này cố gắng thiết lập như một tiêu chuẩn công nghiệp được chọn cho sự lựa chọn của bạn # 1.

---

Bounty Câu hỏi

Để đối phó với các yêu cầu tiền thưởng của "nếu có ai đi # 2 và có thể có bất kỳ sự cải thiện về nó?", Có một mẫu thiết kế từ Pragmatic RESTful API cho biết: Thao

Validation errors will need a field breakdown. This is best modeled by using a fixed top-level error code for validation failures and providing the detailed errors in an additional errors field, like so:

{ 
    "code" : 1024, 
    "message" : "Validation Failed", 
    "errors" : [ 
    { 
     "code" : 5432, 
     "field" : "first_name", 
     "message" : "First name cannot have fancy characters" 
    }, 
    { 
     "code" : 5622, 
     "field" : "password", 
     "message" : "Password cannot be blank" 
    } 
    ] 
} 

Answer 5

Gần đây, tôi đã làm việc dựa vào API Rest sẽ trả về nhiều cảnh báo hoặc lỗi trong kết quả. Bắt đầu từ Mẫu số 2 của bạn, tôi sẽ sửa đổi nó như sau:

{ 
    "status": 400, 
    "results" : null, 
    "warnings": { 
     0: { 
       // Build a warning message here, sample text to show concept 
       "code": 1 // Specific field validation error code 
       "message": "It is no longer neccessary to put .js on the URL" 
      } 
    } 
    "errors": { 
     0: { 
       "code": 2 // Specific field validation error code 
       "message": "Field \"x\" is missing from the array structure" 
       "developer_message": "The request structure must contain the following fields {a,b,c{x,y,z}}", 
      }, 
     1: { 
       "code": 3 // Specific field validation error code 
       "message": "Incorrect Format for field \"y\"", 
       "developer_message": "The field \"y\" must be in the form of \"Y-m-d\"" 
      } 
     } 
    } 

Điều này sẽ cung cấp cho bạn khả năng cung cấp kết quả, với nhiều cảnh báo hoặc lỗi khi cần thiết trong phản hồi của bạn.

Và có, điều này có một số bloat trong cấu trúc, nhưng nó cũng cung cấp một giao diện dễ dàng cho một nhà phát triển để luôn lấy lại dữ liệu của họ trong cùng một cấu trúc.

Tôi cũng sẽ loại bỏ các mục sau đây như IMHO họ phải ở trong các tài liệu API (làm thế nào để tìm sự giúp đỡ sử dụng một mã lỗi) thay vì trên tất cả các lỗi:

"more_info": "www.api.com/help/errors/2" 
"more_info": "www.api.com/help/errors/3" 

Cùng những dòng tương tự, tôi m không chắc chắn nếu bạn cần cả tin nhắn và developer_message. Chúng dường như thừa và như thể bạn đang cố cung cấp thông báo lỗi người dùng từ API khi người gọi không cung cấp dữ liệu chính xác.

Answer 6

API không dành cho con người. Do đó bạn không cần trả lại các văn bản lỗi chi tiết. Bạn thậm chí có thể trả lại mã lỗi có nghĩa là "tham số bị thiếu". Đừng quên ghi lại nó tốt.