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

本文来自企鹅号 - 21CTO媒体

发表于

我来说两句

0 条评论
登录 后参与评论

相关文章

来自专栏测试开发架构之路

APP测试点总结

1.功能性测试:   ——根据产品需求文档编写测试用例。   ——软件设计文档编写用例。   注意:就是根据产品需求文档编写测试用例而进行测试。 2.兼容性测试...

59670
来自专栏拂晓风起

win 7 Word 2007 插入图表出错。部分图表类型不能和其他图表类型组合,请选择其他图标类型

27730
来自专栏服务端技术杂谈

扫盲贴-分布式数据一致性:两阶段提交,三阶段提交

分布式一致性 分布式系统中,为保证数据的高可用,通常将数据保留多个副本,这些副本放置在不同的物理机上。 什么是数据一致性 在数据有多副本的情况下,如果网络,服务...

71760
来自专栏carven

体验koa

之前使用nodejs开发后台服务,使用的一直是express。 后来了解到express开发团队重新开发了一个框架koa。

9800
来自专栏微信小程序开发

开发小程序被问到最频繁的问题(下)

连胜老师在自己的微信小程序开发群里,也经常帮人解答问题,在这里整理一下最频繁被问到的小程序问题。本篇是《开发小程序被问到最频繁的问题(上)》的续篇。 9、用户不...

1.2K90
来自专栏微信小开发

整合微信小程序的Web API接口层的架构设计

来源:伍华聪 cnblogs.com/wuhuacong/p/7267333.html 例如:《C#开发微信门户及应用--微信各个项目模块的定义和相互关系》介绍...

465100
来自专栏Java架构沉思录

CDN为什么这么快

CDN全称:Content Delivery Network或Content Ddistribute Network,即内容分发网络。

52020
来自专栏Eternally运维

FinalShell – SSH终端,同屏SFTP,同步目录切换一体化服务器管理

简介 FinalShell是一体化的的服务器,网络管理软件,功能强大的开发,运维工具,充分满足开发,运维需求.

28210
来自专栏pangguoming

mysql分布式数据库中间件对比

目前数据库中间件有很多,基本这些中间件在下都有了解和使用,各种中间件优缺点及使用场景也都有些心的。所以总结一个关于中间件比较的系列,希望可以对大家有帮助。

47110
来自专栏JackeyGao的博客

数据可视化系统NGraph相关功能截图

去年重写了报表系统并为之取名为NGraph, 目的是做一套可以通过API提交数据来生成可视化数据的系统。

10510

扫码关注云+社区

领取腾讯云代金券