如何正确设计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 ）。 这样，客户可以使用通用实用程序来了解它是否成功，并采取相应的措施。