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.

根据经验和评估多个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"
            }
         ]
      }
   }
}

从消费者的角度来看，只为他们提供文档中的响应和描述所需的数据。

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

REST API抽象资源属性？

1 个答案: