集成第三方API学到的经验教训

原文：Lessons learnt from integrating with 3rd-party API’s
作者：Damon Swayn
翻译：王江平

几乎每个使用InSite进行客户分析的人也都有某种类型的CRM来管理和记录他们的客户交互情况。我们在 InSite的部分工作是丰富已经拥有的数据，可以深入分析客户与你的网站和其他营销材料的交互情况。为了提供这项服务，我们花费大量时间将现有的CRM整合到InSite中， 方便在任何平台上使用，这样，无论你使用什么平台，都可以根据实际需求来帮助客户做出正确的决策。

在我们努力提供这些整合的工程中，遇到了众多大大小小的CRM，并最终与管理这些CRM的供应商取得合作，以提供最佳的结果。

多平台整合并不是一件容易的事情，即使两家公司使用完全相同的CRM，人们也会以不同的方式存储和构造各自的数据，拥有各自的语言和语法来描述数据类别的含义，并希望其他工具以一种最熟悉的方式工作。这是一件合理的事情，许多公司花重金和大量时间建立起了存储在CRM上的数据，所以从根本上改变他们的工作方式是非常困难的。

以下是我在整合过程中的一些分享：

一: 文档是关键

我们整合的许多平台都极少或根本就没有提供有关其API工作情况的文档。实际上，CRM的唯一文档只能通过向URL发送操作请求来访问，这将返回一个伪YAML类文档，告诉我们对象中有哪些字段，但不是如何获取或搜索这些对象。

可以理解的是，有些公司并不想花费大量时间来发展和记录他们的API，而是浪费时间和精力来担心其他公司会窃取资料。 然而，花时间正确构建和记录API是很有必要的，因为，您的客户将要求您向第三方提供API访问， 如果第三方因为你糟糕的设计或文档质量问题而无法完成工作，这将是你的失职。

二: “内部使用”陷阱

在这个javascript无处不在和single-page applications(译者注：一种Web Application，完全地在浏览器上执行。也就是说，标准的SPA程序是不需要网络联机的)流行的时代，越来越多的人转而通过API获取应用程序数据，该API通过某种形式的Javascript获取和呈现到页面中。因此，许多公司已经在其后端数据提供商中首先采用API，并认为如果需要，他们只会向第三方提供同一个API的访问。

这里的问题是，许多开发人员陷入了一个为了Javascript的应用而构建API的陷阱。举个例子，我们整合了一个CRM，而获取访客的备注/评论的唯一方法是调用事件流API，返回的不仅有备注，还有大型HTML框架的广告邮件，以及客户反应的一堆无用数据。导致的结果是，没有得到简单的反馈，而是接收到的是一堆杂乱的数据，而这堆数据里面仅仅只有5%是我们所需要的。当我们有机会看到CRM Web界面如何工作时，就会明白API被设计成这样的原因，因为联系人数据被显示为事件流。

我不是说构建API用于内部使用有什么问题。 事实上，我已经做到了这一点，在这种情况下，让服务器将数据处理成正确的结构更合理，而不是为应用程序前端添加另外一件事情。 但是，我恳求开发人员应该考虑到其他人如何使用您的API，而不是将您的API绑定到您的前端。

教训三: 轮询不是“实时的”

当涉及提供与其他应用整合时, API并不是一个好的妙招。但是API在两个方面比较擅长，它们是：
     1.发送创建/更新/删除操作并立即执行
     2.在特定时间点提供所请求数据的快照

在整合方面的问题是“在特定时间点”，特别是你想让你的整合达到实时。在你所有的API访问都需要实时数据集成的情况下，轮询是最好的方法。某些API通过提供一种将API结果过滤，与上次访问API的数据进行比对的方式使轮询更容易一些。然而， 大多数不这样做, 这意味着不仅必须实现预定轮询， 而且您现在必须存储并跟踪从API返回的数据，并对已更改的数据进行筛选 (哈希是一个很好的选择)。

此问题的解决方案是提供RESTful Web-Hooks的一些方法，每次更新或创建记录时都会触发。 Web-Hooks将允许你提供HTTP回调URL，该回调URL将在触发回调时接收POST请求，这意味着Web-Hook接收方将以互联网的形式实时接收数据的更改。

另一个好处是Web-Hooks将产生和消耗，并大大简化了处理整合所需的逻辑。 Web-Hook消息的生成只是一个出站的HTTP POST请求，基本上可以一旦发送就被遗忘，用户只需要设置一个接收URL来解压缩并处理POST数据。 对于我们来说，该URL解压缩POST数据，将其转换为通用格式，然后在处理程序可用时将其推送到我们的异步处理任务队列，以便在处理和写入数据库时我们的Web服务器层不会陷入僵局。

教训四: 日志记录和限速

构建集成的难点在于它们处于其核心的分布式系统中，而且如果出现任何问题，分布式系统会很难进行调试。

无论你做了多少测试，自动测试或其他方式的测试，这一切都无法捕捉到一个改变JSON密钥的API，或者在它发生之前删除一个 http 报头，在这种情况下，你需要做好准备。

就个人而言，当在集成代码中的关键点前后进行记录时，我发现大量的日志记录是以一种或多种不同的断言方式来验证您的前后条件。这不仅可以让您准确识别出错的位置，还可以让您先检查数据并发送方法调用，这意味着您可以准确地查看可能导致的问题。

为什么提及与日志记录相同类别的速率限制？ 那么，如果你是提高了API速率限制，这将会是个糟糕的设计决策，速率限制太低，不能合理使用，或者更有可能出现错误在您的代码中，导致毫无意义的API调用。为了区分这一点，当您以某种方式进行远程API调用时，应该始终进行日志记录，
允许聚合API调用的频率以及调用的位置，根据我的经验，只要能够识别出对一个API端点 调用次数比其他任何一个点都要多，就可以 API提供商参与之前找到并解决问题，并告诉你是否达到速率限制点。