如何设计开发好一个 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