🌚

设计RESTful API的几个原则

Posted at — Apr 21, 2017
#编程

REST不是一项技术,而是一种设计风格。它的核心思想是实现一种清晰明确的语义,用来描述Web操作。包含两个主要因素:HTTP动词和资源地址。

HTTP动词的使用原则

参与Web操作的HTTP动词主要有GET、POST、DELETE、PUT、HEAD、PATCH。实际上,几乎所有的操作只需GET和POST就可以实现,为什么还要有其它几种呢?目的就是为了实现清晰明确的语义:DELETE /api/v1/post/18肯定比GET /api/v1/post?id=18&action=delete更清楚。

因此HTTP动词使用的重点在于明确语义。例如更新操作,很多文章会说创建资源用POST、修改用PUT,实际上是对REST风格理解不透彻。

总体上,HTTP动词分为两类:幂等和非幂等。幂等是个数学概念,对于一元操作,如果它作用于任一元素两次以上后所得的结果和第一次相同,就认为它是幂等的。简单地说,如果一个接口,传递同样的实参,多次请求的结果和一次没有不同,就认为它是安全的、幂等的,反之,就是不安全、非幂等的。

GET、DELETE、PUT、HEAD是幂等操作,POST和PATCH是非幂等操作。因此,修改操作用POST还是PUT,要看操作本身的幂等与否。举个例子,对于修改用户描述的接口,调用任意次得到的结果都是相同的,所以它是幂等的,应该用PUT。而对于修改用户登录积分的操作,假设每次登录加十分,重复调用会导致分数重复增加,这就是不安全、非幂等的,应该用POST。

资源地址的命名原则

资源地址是对被操作资源位置的描述,因此应该有以下几个原则:

对于前两个,因为对资源的操作已由HTTP动词表述,资源地址里不应该存在动词,否则会造成语义的混乱。此外,不存在动词也就不需要使用驼峰风格。例如,GET /api/v1/getUser/89,「get」在语义上就重复了。

关于资源名称用复数的原则,主要是为了API在风格上的统一,同一种资源用同一个单词表示,单、复数用资源的id表示,URI里有id的就是单数,否则是复数。

结论

REST是风格而不是技术,出bug的可能性不大,并不是能实现业务逻辑、没有bug就是好代码。风格错了,连REST都不算。