Restful风格api设计(HttpMethod)

这篇文章主要是讨论对于各种业务需求如何选择 HttpMethod,一般来说HttpMethod的选择应该和URL一起考虑,所以这里也有涉及,但是主要是讨论HttpMethod

写操作

对于某些记录用户操作的系统(特别是还提供了对操作记录的查看)而言,有些应该是读的操作变成了写操作,例如电商中的搜索,也许有人说应该从这个操作的原意或者业务含义来考虑这个操作是否是写,但是如何判断原意又变成了见仁见智的问题,一般来说程序员之间很难在业务上达成一致,我这里提供一个更加精确的定义:如果一个接口的调用会导致另一个原本能调用成功的接口的调用失败,那么这两个接口都是写操作,为什么一定要失败,而不是使用改变呢,因为写操作很可能导致改变.之前我想到的办法是一个用户的操作能否导致另一个用户能感知到这个定义,但是感知又变成了玄学,例如可以通过页面查看就是一例.
上面这个定义可以确定编辑和删除的情况,但是对于新增的情况有点无能为力,因为在POST之前,一些资源是不存在的,必然就不会有原本能调用成功的接口,如果反过来定义导致原本调用失败的接口调用成功呢?这样看来应该也是写操作,毕竟这改变了状态机的状态,但是这样的是否是POST操作呢?

修改

这两个接口都是修改操作,其最大的区别得救PUT是幂等的而PATCH不是,这样看上去PATCH用于以下两种情况比较合适

• 原字段是数组类型
  在这个数组上添加元素,这样只需要把新增的元素传过来而无需考虑数组原有元素,对于删除操作一般是使用PUT把结果传过来
• 原字段是数字类型
  这样就出发了加法操作,如果想减少则传过来负数即可
  问题是有的时候会指定结果和指定过程都存在,则难以选择

禁用

这个主要用于禁用和删除的情况,特别是没有删除的禁用情况.这里的禁用一般是指除了在主维护页面其他地方,一般是操作的下拉框等都不会出现,对于查询的下拉框可能会出现.另外有的时候禁用状态还可以再执行启用操作.我们先跳过禁用看下启用如何来操作,一般是这样的URL:

POST /account/{id}
PUT /account/{id} -d {“isEnabled”:true}

对于PUT方案的缺点是会和其他操作的URL冲突,而POST方案则没有这个问题.不过如果PUT对于不同业务采用了类SOAP的方案也可以为启用指定专有的URL,例如

PUT /account/{id}/enable -d {“isEnabled”:true}
PUT /account/{id}/enable -d true

如果采用上面哪种方案,都可以解决URL征用的问题,但是这样和业务上出现不一致.特别是对于禁用操作有约束条件的情况.
如果采用了上面的POST方案,也有两种细分

POST /account/{id}
POST /enabled-account/{id}

对于第二种似乎语义更明确,但是这种准确也带来了复杂性暴露了出来,因为一般GET操作是如下格式的

GET /accounts
GET /account/{id}

而enabled-*格式的URL就与GET不一致了,如果采用了这种方案就需要把GET的url同时做出变更
另外采用DELETE的一个问题是无法携带更多的信息,当然,对于DELETE操作而言,如果这个记录真的被删除了,那么也就查不到了,也就不用携带信息了.