定义资源

在Fielding的论文中，资源被描述为：

“可以命名的任何信息”……“文档或图像，临时服务（例如，“洛杉矶今天的天气”），其他资源的集合，非虚拟对象（例如，人） 等等。 换句话说，任何可能成为作者超文本 引用 目标的概念都 必须符合资源的定义。 资源是 到一组实体 的概念性映射 ，而不是在任何特定 时间 点对应于该映射的实体 。”

定义资源既是科学也是艺术。它需要领域知识和API体系结构技能。下面详细介绍的以下几点用作清单，可以帮助您确定资源。

资源必须包含业务说明

商业描述应为简单散文中的3-4个句子，以说明资源是什么。
对您的系统有一定了解的开发人员应该能够理解该描述
资源的任何警告均应明确

资源应单独使用

这类似于定义微服务边界的准则，在这种情况下，应将微服务视为自身有用。同样，资源应单独使用。

例如，代替：

 /street-address/{id}  RESPONSE  { "street1" : "String" , "street2" : "String"  }

和

 /address-extra/{id}  RESPONSE  { "city" : "String" , "country" : "String"  }

它应该是：

 /address/{id}  RESPONSE  { "street1" : "String" , "street2" : "String" , "city" : "String" , "country" : "String"  }

如果资源本身没有用，并且总是需要后续请求，则意味着代码将不可避免地变得更加复杂，并且第二个请求将对性能造成影响

使用适当的名词

最好使用简单名词而不是复合名词。例如，
地址优于AddressInfo或AddressDetail 。这是一条一般规则，总会有例外。

如果使用多个资源表示同一数据的不同视图，例如： Address和AddressDetail ，则使用简单名词，例如
地址第一。然后，如果第二种表示形式更详细地使用
ResourceNameDetail，或者如果不够详细，请使用ResourceNameSummary 。例如，假设需要引入一个地址类型资源：

地址首先介绍
如果需要更详细的地址后续视图，则新资源应称为AddressDetail
如果需要的后继地址视图不太详细，则新资源应称为AddressSummary

如果仅在READ中使用它，它是否需要成为资源？

如果仅在读取请求中使用过资源，而从未在写入（ 创建，部分更新，完全更新，删除等 ）请求中使用过资源，则是否需要将其定义为具有自己的URI的资源是可疑的。可以将其添加到父负载中，如果担心负载会变得太复杂，则父可以仅提供一个稀疏查询-客户端可以根据API请求确定要返回的内容。

资源应符合统一接口

统一的接口是良好API设计的重要组成部分。如果创建，读取，更新，删除等操作以一致的方式进行，则意味着代码更加一致，可重用且更易于维护。

这表示：

 GET /addresses/{id}

和

 GET /addresses

必须返回相同的地址数据结构来表示一个地址。

 GET /addresses/{id}  RESPONSE  { "id" : "546" , "street1" : "String" , "street2" : "String" , "city" : "String" , "country" : "String"  }

和

 GET /addresses  RESPONSE  { "elements" : [ { "id" : "546" , "street1" : "String" , "street2" : "String" , "city" : "String" , "country" : "String" }, ... ]  }

同样，对于写入有效负载，数据结构应该相同。因此，更改street1的部分更新将是：

 POST /addresses/{id}/edit  REQUEST  { "street1" : "Walkview"  }  RESPONSE  { "id" : "546" , "street1" : "Walkview" , "street2" : "Meadowbrook" , "city" : "Dublin" , "country" : "Ireland"  }

而不是像

 POST /addresses/{id}  REQUEST  { "newStreet1Value" : "Walkview"  }

从资源的角度来看，数据结构必须一致。不同的数据结构意味着不同的资源，应使用不同的名称命名并具有自己的路径。

不要暴露一切

如果您的数据库模型非常复杂，则不需要在API级别公开所有属性。有些字段只能保留用于后台处理，而不能显示在UI上。此类属性永远不应包含在JSON API中。

在将属性添加到JSON资源时，请考虑：

API中应仅公开您确定客户端感兴趣的字段
如果不确定，请忽略该属性。稍后添加属性，然后删除已经公开的属性的风险要低得多。

API模型不应盲目地反映数据库关系模型或OO模型

在数据库建模方法中，使用规范化数据或折叠继承层次结构。在面向对象的设计中，诸如多态，继承层次结构等技术被用于促进诸如代码重用之类的事情并减少耦合。

资源建模不必遵循这些技术。 API的使用者不关心数据是全部放在一个表中还是在多个表中进行了规范化。通常，API以易于使用的格式返回数据，并且在客户端变得有用之前不需要客户端进行太多其他映射。

使用分层数据避免重复

与诸如CSV之类的平面格式相比，分层数据的优点之一是它提供了一种避免重复的机制。例如，考虑一个数据结构，其中包含人员列表以及他们所在的团队。在CSV中，这是：

 team, firstname, lastname  Liverpool, Mo, Salah  Liverpool, Andy, Roberston

在JSON中，可能是：

 { "team" : "Liverpool" , "players" : [ { "firstName" : "Mo" , "lastName" : "Salah" }, { "firstName" : "Andy" , "lastName" : "Roberston" }, ... ]  }

使用分层数据使上下文清晰

分层数据的另一个优点是它有助于提供上下文。要了解平面数据结构，您需要了解生成数据结构的查询是什么，以了解其含义。例如，考虑一堆包含日期范围的行。

 name, fromDate, toDate, holidays  Tony, 2018 - 01 - 01 , 2018 - 02 - 02 , true  Tony, 2018 - 02 - 03 , 2018 - 03 - 01 , false

您可以假设当Tony休假时会有新的一行。但是如果还有另一列怎么办

 name, fromDate, toDate, holidays, sick,  Tony, 2018 - 01 - 01 , 2018 - 02 - 02 , true , false  Tony, 2018 - 02 - 03 , 2018 - 03 - 01 , false , true

日期范围是否对应于假期，疾病或两者兼而有之？

如果我们能获得更多数据，也许会更清楚……

 name, fromDate, toDate, holidays, sick,  Tony, 2018 - 01 - 01 , 2018 - 02 - 02 , true , false  Tony, 2018 - 02 - 03 , 2018 - 03 - 01 , false , true  Tony, 2018 - 03 - 02 , 2018 - 04 - 01 , false , false

现在看来，日期范围所对应的是一种病，这只是一个巧合，它排列了一个假期。但是，当我们获得更多数据时，此理论将失败：

 name, fromDate, toDate, holidays, sick,  Tony, 2018 - 01 - 01 , 2018 - 02 - 02 , true , false  Tony, 2018 - 02 - 03 , 2018 - 03 - 01 , false , true  Tony, 2018 - 03 - 02 , 2018 - 04 - 01 , false , false  Tony, 2018 - 04 - 02 , 2018 - 05 - 01 , true , false

平面数据结构的问题在于，只能使数据自我描述。如果没有任何信息，它将变得更加复杂。例如：

 name, fromDate, toDate, holidays, sick,  Tony, 2018 - 01 - 01 , 2018 - 02 - 02 , true , false  Tony, 2018 - 02 - 03 , 2018 - 03 - 01 , false , true  Tony, 2018 - 03 - 02 , 2018 - 04 - 01 , false , false  Tony, 2018 - 04 - 02 , 2018 - 05 - 01 , true , false  Tony, 2018 - 05 - 02 , 2018 - 06 - 01 , null , false  Tony, 2018 - 06 - 02 , 2018 - 07 - 01 , null , false  Tony, 2018 - 07 - 02 , 2018 - 07 - 08 , true , false  Tony, 2018 - 07 - 08 , 2018 - 07 - 09 , true , null

不可避免的是，处理该数据将是错误的。我们可以用以下分层格式表示相同的数据：

 { "name" : "tony" , "holidays" : [ { "fromDate" : "fromDate" "2018-01-01" , "toDate" : "2018-02-02" }, { "fromDate" : "fromDate" "2018-04-02" , "toDate" : "2018-05-01" }, { "fromDate" : "2018-07-02" , "toDate" : "2018-07-09" } ], "sick" : [ { "fromDate" : "2018-02-03" , "toDate" : "2018-03-01" } ]  }

现在，数据更加自我描述。很清楚，日期范围是假期还是病假。

资源关系

资源本身只能描述自己。资源模型描述资源之间的关系。这将表明：

资源之间的依赖关系。存在特定资源需要哪些资源，或者当特定资源发生更改时会影响哪些资源：更新或删除。
数据导航–在大域模型中，如果向模型的使用者提供导航和方向感，则更容易理解和遵循。尤其是何时进行导航（资源松散连接）与向下导航（资源牢固连接）可以区分开

资源不仅应该考虑实现HATEOAS的超媒体链接；当资源使用超媒体链接描述它们所链接的内容时，它是表达资源模型的一种非常强大的机制。优势包括：

它将大型域模型分成更易于管理的部分。通常，用户只对模型的特定部分感兴趣。当“资源”自己描述自己的关系时，这意味着将一个大型的复杂模型分解为易于消化的部分，并且用户可以更快地获取所需的信息。
资源模型是自我描述的，并与代码保持同步。一切都在同一地点。

明确父母与子女的关系

子级自我描述了父级URL层次名称间距。父资源具有一种或多种类型的子代，应通过提供指向子代的链接来阐明这一点。例如，如果一个团队有一个玩家。团队有效负载应对此进行明确说明。

 REQUEST  https: //api.server.com/teams/4676  RESPONSE  { "id" : "34533" , ..., "_links" : { "self" : " https://api.server.com/teams/4676 " , "players" : " https://api.server.com/teams/4676/players " }  }

明确对等关系

这与上面的类似，只不过它用于存在于不同层次名称空间中的资源。因此，例如，假设团队在部门1中。应该在团队的部门属性中包含一个链接。

 REQUEST  https: //api.server.com/teams/4676  RESPONSE  { "id" : "34533" , "division" : { "name" : "Division 1" , "_links" : { "self" : " https://api.server.com/divisions/1 " } }, ..., "_links" : { "self" : " https://api.server.com/teams/4676 " , "players" : " https://api.server.com/teams/4676/players " }  }

明确链接到其他表示形式

如果将数据建模为具有多个代表数据不同表示形式的资源，则这些资源还应包括彼此的链接。

 REQUEST  https: //api.server.com/teams/4676  RESPONSE  { "id" : "34533" , "division" : { "name" : "Division 1" , "_links" : { "self" : " https://api.server.com/divisions/1 " } }, ..., "_links" : { "self" : " https://api.server.com/teams/4676 " , "players" : " https://api.server.com/teams/4676/players " , "teamDetails" : " https://api.server.com/teamDetails/4676 " }  }