从语义学角度看API设计的URIs

REST全称为Representational State Transfer（直译为：表现层状态转移）是许多软件程序（如网页应用facebook、百度、淘宝等，云服务openstack等）遵循的设计原则。基于REST的API接口测试几乎是每个测试工程师步入“自动化测试”大门的第一阶段。但是从设计角度出发，不论是开发工程师还是测试工程师几乎很少关注REST的URIs设计合理性、可读性、直观性等等。

本文从语义学的角度出发，浅谈测试工程师测试REST的API接口时应该关注的设计要点。

1. 有条理的vs无条理的URIs

REST中的URIs应该有条理且易读的。一个有条理的URI的资源名应该是小写字母、没有扩展名、下划线或斜杠。相反，无条理的URI资源名包括大写字母、特殊符号等等使人难以理解和阅读。如下表所示：www.exampleAlbum.com/NEW_Customer/image01.tiff/包含大写字母、文件后缀和反斜杠结尾，该URI违反语义学模式，不建议使用✖；与之相反的www.example.com/customers/1234符合语义学的条理标准，建议使用✅。

2. 有上下文语义的vs无上下文语义的URIs

URI中的节点应该是上下文关联的，因此URI中的节点应该有具有相同上下文语义的资源名组成。如下所示，www.example.com/newspapers/planet/players?id=123不满足上下文语义关联原则。因为newspapers、planet、players不属于同一语境。相反，www.example.com/soccer/team/players?id=123则满足上下文语义关联原则，soccer、team、players属于同一语境下的不同对象。

3. 无动词的vs包含CRUDy的URIs

CRUD指的是CREATE、READ、UPDATE、DELETE或其他意思相近的动词。合适的HTTP方法，如GET、POST、PUT、DELETE、UPDATE的URIs中不应该包含其他CRUD动词。如下所示，某个HTTP POST方法的URI为www.example.com/update/players/age?id=123，该URI违反了CRUDy原则，因为POST方法中又包含了update动词。

4. 有层次的vs无层次的URIs节点

设计优良、清晰的URI应该是节点层次分明的。URI中的节点应该同它的相邻节点具有等级关系。相反，无层次的URI节点指的是URI中至少存在一个两个相邻节点不存在层次关系。如下所示www.examples1.com/professors/faculty/university中的professors、faculty、university虽然存在层次关系（从小到大），但不符合语义学、实际场景中university>faculty>professors关系。相反，www.examples2.com/university/faculty/professors则满足层次合理性原则。

5. 单数vs复数URIs节点

URI设计应该谨慎、正确地使用单数和复数含义的节点。例如：客户端发送HTTP PUT或DELTE请求时，URI的最后一个节点应该使用单数语义；相反的HTTP POST请求的最后一个节点应该使用复数语义。为何会有这样的建议呢？因为PUT和DELETE请求多用于修改和删除操作，而在实际应用中我们针对修改和删除操作都需谨慎，最后一个节点使用单数语义表明针对“某一个”资源进行操作而不是“某一批”资源。指的注意的是，根据REST的幂等原则，HTTP GET请求不受该原则限制，因为GET请求不会改变资源的内部状态。如下所示，HTTP DELETE请求，建议使用www.example.com/team/player而不是www.example.com/team/players。

6. 有版本的vs无版本的URIs节点

随着软件版本的不断迭代，APIs也会有出现不同版本的差异，如果使用不正确版本的APIs则会造成客户端请求的失败。具有版本控制的APIs能够帮助客户端管理APIs和客户端更好地使用APIs。如下表所示：api.example.com/resourceid/view这一URI里不包含任何地版本提示，从语义学易于理解的角度出发，可使用性低于包含版本节点的api.example.com/1.1/resourceid/view URI。

7. 标准的vs非标准的URIs节点

除了以上几点，URIs设计的最重要一点是节点或资源的定义和使用应该标准化、唯一性和可理解性。URI设计时不应该加入特殊字符如!、@、#等，不应该出现空格符，双连接符—等等。如下所示api.example.com/museum/louvre/r′eception/显然违反这一原则。

从语义学角度理解API URIs的设计要点，可以帮助开发工程师或测试工程师遵循一定的设计原则进行设计和测试。虽然不规范的URIs设计从功能上不会影响使用，但从易于理解和可使用性角度而言，规范化的URIs更具优势。