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.

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

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

不要单独调用以提供更多详细信息，如果您更改版本