REST API抽象资源属性？

Question

从使用者的角度来看，抽象资源属性以使字段自描述是否有任何价值？ 还是应该由文档处理。

这个想法是，每个属性都将包装在一个更复杂的对象中，该对象将提供fieldId，fieldType和值。 使每个字段更具描述性。

另外，Web服务将包括另一个端点，以进一步描述每个字段。

因此，而不是以下内容：

{
   "id":123,
   "type":"person",
   "attributes":{
      "name":"John Smith",
      "dateOfBirth":"2000-01-01",
      "ssn":123456789
   }
}

json看起来像这样：

{
   "id":123,
   "type":"person",
   "attributes":[
      {
         "fieldId":"name",
         "dataType":"string",
         "value":"John Smith"
      },
      {
         "fieldId":"dateOfBirth",
         "dataType":"date",
         "value":"2000-01-01"
      },
      {
         "fieldId":"ssn",
         "dataType":"integer",
         "value":123456789
      }
   ],
   "relationships":{
      "dataType":{
         "links":{
            "related":{
               "href":"http://acme.com/ws/dataTypes/"
            }
         },
         "data":[
            {
               "id":"string",
               "type":"dataType"
            },
            {
               "id":"date",
               "type":"dataType"
            },
            {
               "id":"integer",
               "type":"dataType"
            }
         ]
      },
      "field":{
         "links":{
            "related":{
               "href":"http://acme.com/ws/fields/"
            }
         },
         "data":[
            {
               "id":"name",
               "type":"field"
            },
            {
               "id":"dateOfBirth",
               "type":"field"
            },
            {
               "id":"ssn",
               "type":"field"
            }
         ]
      }
   }
}

然后，链接到的dataType资源将提供一些描述和/或格式：

{
   "id":"ssn",
   "type":"field",
   "attributes":{
      "valueType":"string",
      "description":"Social security in the xxx-xx-xxxx format."
   },
   "links":{
      "self":{
         "href":"http://acme.com/ws/fields/ssn",
         "meta":{
            "httpMethod":"GET"
         }
      }
   }
}

{
   "id":"date",
   "type":"dataType",
   "attributes":{
      "valueType":"string",
      "description":"yyyy-MM-dd"
   },
   "links":{
      "self":{
         "href":"http://acme.com/ws/dataTypes/date",
         "meta":{
            "httpMethod":"GET"
         }
      }
   }
}

Answer 1

回答这个问题From the perspective of a consumer, is there any value in abstracting resource attributes to make the fields self-describing? Or should the documentation handle it. From the perspective of a consumer, is there any value in abstracting resource attributes to make the fields self-describing? Or should the documentation handle it.

• 根据经验并评估多个api，该api应该只发送所需的数据。 没有相应的点处理描述，需要文档注意。

• 另外，请考虑发送仅用于描述字段的额外数据量

• 另外，前端（例如javascript）需要解析对象，通过仅发送所需数据来节省时间

考虑这个占用的带宽

{
   "id":123,
   "type":"person",
   "attributes":{
      "name":"John Smith",
      "dateOfBirth":"2000-01-01",
      "ssn":123456789
   }
}

与庞大的数据相比

{
   "id":123,
   "type":"person",
   "attributes":[
      {
         "fieldId":"name",
         "dataType":"string",
         "value":"John Smith"
      },
      {
         "fieldId":"dateOfBirth",
         "dataType":"date",
         "value":"2000-01-01"
      },
      {
         "fieldId":"ssn",
         "dataType":"integer",
         "value":123456789
      }
   ],
   "relationships":{
      "dataType":{
         "links":{
            "related":{
               "href":"http://acme.com/ws/dataTypes/"
            }
         },
         "data":[
            {
               "id":"string",
               "type":"dataType"
            },
            {
               "id":"date",
               "type":"dataType"
            },
            {
               "id":"integer",
               "type":"dataType"
            }
         ]
      },
      "field":{
         "links":{
            "related":{
               "href":"http://acme.com/ws/fields/"
            }
         },
         "data":[
            {
               "id":"name",
               "type":"field"
            },
            {
               "id":"dateOfBirth",
               "type":"field"
            },
            {
               "id":"ssn",
               "type":"field"
            }
         ]
      }
   }
}

从消费者的角度出发，仅在文档中以响应和描述的方式向他们提供所需的数据。

而且不要单独要求提供更多详细信息，如果您更改版本，将很难维护