如何正確設計REST API響應？

Question

在某些情況下，我們有一個休息端點，並且響應會根據應用程序流程而有所不同。 json內的屬性會有所不同，所以問題是我們是否需要一個包含json的響應，該json的結構將取決於應用程序流。

我現在看到的基本上有三個選擇。 我們可以有兩個屬性，並且其中一個屬性將始終為null（customer或businessCustomer）：

{
  "data": {
    "target": "Business",
    "customer": null,
    "businessCustomer": {
        ....
    }
}

{
  "data": {
    "target": "Customer",
    "customer": {
        ....
    },
    "businessCustomer": null,
}

否則，我們只有一個屬性，該json對象的內容將有所不同（總是填充客戶）：

{
  "data": {
    "target": "Customer or business",
    "customer": {
        ....
    }
}

我認為可能很難僅使用一個屬性來消耗數據。 如何在強類型語言中流暢地序列化它？

哪種方法最好？ 提前致謝！

Answer 1

我們在開發過程中遇到了類似的情況，並使用資源類型對其進行了解決，並為其所有子類型創建了一個基類。 這是一個通用實現，客戶端代碼負責檢查@type並從其一側創建相應的對象。

CustomerResource (Considering this as Base Class)
    BusinessCustomerResource (Extended from Customer Resource)

對於企業客戶資源：

{
    "someOtherElement": "value",
    "customer" : {
                    "@type" : "BusinessCustomerResource",
                    "faxNumber" : "35635636",
                    "email" : "test@gmail.com",
                    "phone" : "2503334444",
                    "contactName" : "name",
                    "firstName" : "Owner",
                    "lastName" : "lastName"
                    ...
                    "address" : {
                      "@type" : "InternationalAddressResource",
                      "province" : "AB",
                      "country" : "Canada",
                      ...
                    }
                }
}

對於客戶資源：

{
    "someOtherElement": "value",
    "customer" : {
                    "@type" : "CustomerResource",
                    "email" : "test@gmail.com",
                    "phone" : "2503334444",
                    "firstName" : "Owner",
                    "lastName" : "lastName"
                    ...
                    "address" : {
                      "@type" : "PostalAddressResource",
                      "province" : "AB",
                      "country" : "Canada",
                      ...
                    }
                }
}

Answer 2

我建議使用通用的響應格式。 您可以在現實世界中觀察到類似的示例（示例：HTTP請求/響應）。

您可以像下面這樣對它進行標准化：

{
  "statusCode": 0,
  "statusDesc": "Response description",
  "value": null
}

在這里， statusCode和statusDesc在所有響應中都是通用的，並且值會根據api發生變化（在您的情況下，您可以分別傳遞customer或businessCustomer ）。 這樣，客戶可以使用通用實用程序來了解它是否成功，並采取相應的措施。