如何设计开发好一个 HTTP API?

在过去的几年里,我使用着各式各样的HTTP API。这些API通常不是公开的,只是提供给合作伙伴公司。此外,我也看了很多开发者提供的API,自己也参与了几个API的开发。这些API经常有设计缺陷,使得API的可靠性与可集成性变得有点困难。

我想说常出的问题主要是重复创建资源。资源创建必须与关键的实际操作(如付款)绑定在一块。

让我们以Paypal的Create Payment API为例:

当我们创建一个新的付款资源。(我们向/v1/payments/payment发出POST请求),Paypal则立即向用户收费。如果交易成功,则返回状态码201以及补充Id。这意味着,如果在发送请求时遇到网络问题中断,会拿不到付款Id,因此也无法轻易判断付款是否成功。更糟糕的,如果我们有一个发现网络错误的自动重试机制,这会向用户发生二次收费。

当然,这是API的一个已存在的问题,Paypal提供了一个解决方案。我们可以使用PayPal-Request-Id或者使用误写发票号码来取消重复的请求。

但是解决方案真的需要这么复杂么?这两种方式都不是用户友好的:消费者需要有一个可靠的机制来生成相同的请求Id,在第二种情况下,如果你有多张发票的付款,该怎么办?可能还是需要一个更优雅的解决方案。

用POST/PUT 来解决重复资源的创建

如果POST请求数据库记录和资源ID生成以外,就可以轻松地避免这个问题。流程如下图:

POST/PUT的资源创建

有了这个流程,在发生网络故障时很容易重试请求。比如重试POST请求,则只会导致重复的空资源,如果你重试PUT请求,你也是安全的,因为PUT请求是幂等的。

所以我发现,POST/PUT 创建模式更优雅,尽管它需要两次请求才能完全创建一个资源。 你可以并不喜欢这种方法。但是我的观点是,POST 需要支持大规模请求,以适合真实场景。如果你没有提供这样的机制,那么你的API将是不稳定的或不可靠的开发环境。

感谢阅读,希望对大家有帮助。

作者:Alex Rudenko

编译:21CTO社区

地址:https://dev.to/orkon/making-better-http-apis-72l

  • 发表于:
  • 原文链接:http://kuaibao.qq.com/s/20171228B0UGAK00?refer=cp_1026

同媒体快讯

相关快讯

扫码关注云+社区