三种常见的API设计错误及解决方案

时间:2024-04-08 20:53:48

原文:Three common API design mistakes and how to overcome them
作者:Jennifer Riggins
翻译:Vincent

API已经成为了我们生活中很常见的一部分,那么在API设计过程中有哪些容易犯的错误呢?作者在本文介绍了三种,也给出了相应的解决方案,不妨一起来看一下吧!以下为译文。

三种常见的API设计错误及解决方案

作为表单工具Typeform的API领头人,Jason Harmon恰好也与JSON schema同名了,他最近就“哪些因素破坏了生产环境”这个问题在APIdays会议上做了非常积极的讨论。事实上有三个因素。

三种常见的API设计错误及解决方案

API解决方案#1:如何让HTTP POST代替GET

由于人们更喜欢使用HTTP GET进行数据检索,因此这就使得HTTP POST变得并不是那么常见了。虽然使用GET会导致URL变得很长,但是由于它们与大多数查询没有什么不同,因此GET已经成为使用HTTP构建过滤查询的默认方法了。(同样值得注意的是,较长的网址往往更容易被Google发现,所以它们对搜索引擎的优化很有帮助。)

但是由于Web应用程序需要使用浏览器,因此使用GET很有可能会出现问题。根据Harmon的说法,由于浏览器(特别是Chrome)特别容易出现缓存,因此如果出现了一个看似重复的GET请求,那么可能会出现一次请求出现两个着陆页。在Typeform上面,Harmonform和他的团队发现由于已经被浏览器标记为重复,实际上页面已经转储过了。

为了解决这个问题,Harmon建议把GET改为POST,因为在HTTP规范中,POST是不会缓存的。

如果请求的API已经在缓存里了,而你又不知道为什么它会在缓存里面,Harmon建议可以从GET入手查找原因:

  1. 尽可能添加POST(请记住,从GET更改为POST可能会导致API合同发生重大更改)
  2. 将?cache_buster=添加到GET(作为维护合同现状的一种方式,如果在开发人员社区中进行重大更改将会非常困难)

这些措施可以有效控制缓存。

API解决方案#2:如何压缩多次轮询的API

像Web应用程序这样的API消费者们一次又一次地调用某个API时,这就被称为轮询API。这种情况通常发生在API消费者期望定期更改某些数据,并得到最新数据时。例如,在Typeform的某些情况下,集成表单的消费者可以定期轮询API,以便获得表单的结果。API消费者可能会使用Zapier,如果平均每5分钟调用一次,那么网络上面会显示大量的调用。

针对这个问题,Harmon提出了这些疑问:

  • 数据集很大吗?
  • 查询的代价高吗?
  • 数据经常变化吗?
  • 客户端多吗?

“我们也提出了一个快速的解决方案,就是设置webhooks,它是一种反向的API。不是他们主动发起请求,而是当某些事情出现以后,我们主动给他们发送POST,”Harmon说。

他把这种请求之间的差异描述为戏剧性的。

“作为webhooks的客户,整个晚上我只想调用一次API,”Harmon说,为了确保不会错过webhook的交付。他接着说,webhook并不是独立存在的,它与API可以很好地兼容,因为它们减少了所需调用的次数。

除了webhook,他还提供了其他选项:

  • 缓存(但是很难实现)
  • 数据库只读权限的镜像

API解决方案#3:如何使用群组调用来利用普通的调用链。

三种常见的API设计错误及解决方案

每次构建API时,并不是都需要对所有的东西都进行更新,Harmon以Typeform表单的微服务结构化版本为例说明了这一个问题。在Typeform的某些情况下,立即更新所有内容需要7个单独的API调用,这将导致性能瓶颈。现在正在考虑的一种解决方案是将REST用于graphql驱动的方法。与此同时,Harmon说他们开发了以下的替代方法。

正如上面的图片中看到的,团队将表单分解为一个类似于微服务的结构体,该结构体将某些常见的链式后端活动绑定在一起,以便更有效地服务前端。在响应调用时,服务器端JavaScript (Node.js)中的某一层将处理业务流程,从而形成一个面向前端的(BFF)。这是一种将僵化资源结构转化为优势的方法。

三种常见的API设计错误及解决方案

像许多其他情况一样,这种情况关键是要考虑客户端如何执行调用,以及如何使用该工具。Typeform的团队识别了上面看到的模式,他们可以将调用集中到单个链中,比如Form > Design > Background > Image。Harmon说,要关注他所说的N+1调用,比如当客户端可以调用父类时,但是实际上调用了相关条目或者子条目。如果能够识别这样的行为模式,那么就可能会减少API调用的数量,从而提高性能。

Harmon还提到了BFF这种微服务结构体使得新增动作在实时场景中变得容易。不过,他也提出了警告,这是需要提前让用户体验设计师参与进来

站在用户的角度构建API

“构建API时,首先需要考虑的应该是用户应该如何使用。我们称之为API设计,但我们的思考方式更倾向于工程师。“试着跟将要使用API的人产生一些同理心。当真正做到这一点的时候,问题总是可以提前被发现。”

对于开发人员来说这一点很关键,因为这不仅意味着你的客户会继续使用你的API,而且你不活问题和解决问题的能力也会增强,这样才会构建出用户实际上想要使用的产品。

Harmon继续说,这个过程不仅仅是倾听客户,而是要确保在满足客户所有的需求以后,API还能是强大的、安全的和灵活的。

Harmon强调,API设计不仅仅是项目开始时的规范。它也可以解决一些很严重的问题,包括他上面分享的那些“廉价的修复”。所有这些修正首先基于逻辑。

“想想看,在这些电话发生后,会发生什么事情。你怎么读它在你的日志里写的故事?”Harmon问道。

就像所有优秀的客户服务和用户体验创造一样,开发人员的体验可以归结为两件事——倾听你的API消费者是什么,而不是说什么,然后用逻辑来解决他们最大的问题。