在一年半的时间里，我们将API与20个外部服务集成在一起。 前五个集成经历了痛苦和眼泪-我们犯了所有可能的错误。 他们多次重写了代码，并在发布之前就与合作伙伴分开，因为他们不同意改进。 浪费时间和金钱。
但是，对于每个新的集成，我们都提出了针对重复出现的问题的解决方案。 结果，我们使最后一次集成的速度比第一次更快。 现在，我们做的事情有所不同-阅读文章。
为了使您更好地了解我们集成的细节，我们将简要介绍我们的工作。 我们正在开发在线经纪人。 工作原理：用户到现场，填写调查表，我们将其转移到小额信贷组织（MFI），并获得他们的批准或拒绝贷款。 用户选择合适的报价并收到钱。 为了使此功能在线运行，我们通过API与MFI集成。
使用清单和规格评估合作伙伴是否准备好集成
我们将分析两种情况：潜在的合作伙伴何时已经具有用于接受应用程序的API，何时没有。 这两种情况都表明合作伙伴希望与我们集成，并准备花时间在此上。
合作伙伴没有API-我们发送规范
之前，我们以口头或信函方式向合作伙伴说明了集成所需的内容，而合作伙伴基于这些解释制作了一个API，用于接受Finspin的应用程序。 我们对调查表的模型，对象，字段的要求及其验证规则不同意。 快速描述方法的目的和可能的答案。 结果证明与预期的结果是无限遥远的，因为我们对API的理解与合作伙伴关系有很大不同。 我不得不重做一切。
现在 。 我们编写了规范-一个可以在Swagger中打开的YAML文件。 在规范中，我们描述了最适合将Finspin与MFI集成的API：问卷调查字段和验证规则，带有答案的请求格式和类型，方法名称，可能的错误和状态。 我们记录了我们计划接收的应用程序状态的状态，例如：“正在接受处理”，“计分进行中”，“拒绝贷款”，“批准”等。
我们将规范发送给合作伙伴，然后由他决定是否可以提供这样的API。 如果不能，请注意规范中的问题点，例如，并非所有应用程序状态都准备好转移到API或问卷中没有足够的字段。 而且我们已经在讨论特定点，而不是抽象实体。 合作伙伴不会浪费时间来编写文档，而是会调整我们的文档。
我们花了两天的时间来创建规范，但是现在我们在API的批准和改进上节省了数十个小时。 此外，借助规范，我们可以快速筛选出尚未准备好进行集成的合作伙伴。 在早期阶段，很明显我们的在线应用程序处理过程非常不同：集成无利可图。
合作伙伴有一个API-通过清单运行
我们
曾经获得合作伙伴的规格，并在旅途中提出问题。 他们常常忘记澄清一些重要的内容，然后在开发和测试的最后阶段浮出水面，这时修复和重写变得特别昂贵。 不知何故，在与一位合作伙伴集成结束时，事实证明他将通过API转移贷款状态，但要延迟几天。 对于我们来说，这是不可接受的。 伙伴关系必须放弃。
现在 。 我们已经编写了一份清单，以评估API及其服务的过程。 清单收集了必须回答的问题。 首先，我们的经理在规范中寻找答案。 如果找不到，请向合作伙伴提出问题。
该清单可帮助您在开始开发之前而不是在开发之后发现瓶颈，这时您必须编辑代码，而客户会因服务质量差而受苦。
面对新情况，我们会不断补充清单。 清单越详细，在开发中跳过错误的风险越低。
API清单片段术语表
以前，在我们看来，在在线贷款领域，每个人都以相同的方式理解专业术语，不会有任何差异。 实践表明，我们错了。
例如，对于一个MFI，我们对主要客户和重复客户的解释不同。 对于我们来说，主要客户是其个人资料首先通过Finspin进入MFI数据库的客户，而回头客已经在数据库中。 该合作伙伴根据发放的贷款数量来考虑回头客：回头客收到两笔贷款，第三笔。 这种术语上的混淆可能导致财务对帐不一致。
现在，我们使用一些术语表与合作伙伴进行核对。 通常，只需澄清五个或六个基本术语即可同步有关集成的想法并评估合作前景。
术语表一旦帮助我们避免了不利的整合。 我们对“批准”的解释与会员的区别很大。 合作伙伴的“批准”包括许多需要人工处理的方面。 我们追求最大程度的自动化，因此我们立即拒绝合作。
澄清术语“批准”首先是业务，然后是发展
在某些情况下，我们开始与具有规范的潜在合作伙伴合作。 我们的经理收到了规范，仔细研究了该规范，指定了与合作伙伴集成的详细信息，并与开发人员讨论了有争议的问题。 然后，领导层发出一条消息：“结束，整合被取消了，我们对条件没有达成共识。” 员工浪费时间。
当您改变主意并完成工作时现在 ，铁律
已生效：经理只有在收到管理层的明确决定后才开始研究规范。
准备集成：URL，详细信息，环境
以前，对合作伙伴API
的首次调用是在开发服务器对我们的应用程序进行测试期间发生的。 通常，第一个请求在连接设置阶段会收到错误：无法连接到服务器或仅超时。 最受欢迎的原因：
- 方法名称不正确（密封或混淆）
- 无效的网域
- 错误的连接详细信息，
- 我们没有将服务器的IP添加到白名单中。
修复这些小错误花费了数小时，因为它们又一次又一次地出现：在修复一个错误之前，您将看不到下一个。
现在 ，在将任务纳入开发计划之前，我们将通过一个小的清单来阐明访问API的所有功能。 清单列出了需要澄清的要点，例如：
- 服务负载的限制，
- 每单位时间的请求数
- 连接细节
- 通过IP地址列入白名单，
- SSL证书验证
- 流量加密要求
- 请求中的特殊标头
- 是否存在带有API的测试服务器，或者是否能够向战斗服务器发送测试请求
如果有一个测试API，我们肯定会发现访问战斗服务器和测试服务器有什么区别。 在构建从应用程序到开发人员和产品环境中的合作伙伴的请求时，我们会考虑差异。 这些措施有助于我们了解系统是否已准备好满足我们的需求，或者是否需要进行其他调整。
手动将请求发送到API
在此之前，我们立即根据合作伙伴的规范编写了代码，草拟了规范，进行了修改和测试。 并且在集成测试阶段，事实证明并非规范中编写的所有内容都与现实相对应-从请求的格式开始，直到通过应用程序的过程结束。
例如，根据规范，当访问某种方法时，我们期望响应中采用某种格式的响应，为接收到的响应的有效性挂起处理过程，然后进行测试，然后突然在响应中得到一个数组。 我们从合作伙伴的开发者那里找出原因。 他们引用了过时的文档。 同样，进行了一系列的改进，审查和测试。
现在 ，一旦我们收到文档和连接详细信息，便通过API客户端运行该过程。 通常，测试人员将规范上载到Postman，并模拟发送贷款申请的完整业务流程，检查带有不同数据集的最受欢迎案例。 也就是说，手动执行应用程序将执行的操作。
在手动运行阶段，会发现文档中80％的错误。 我们描述错误并传递给合作伙伴。 合作伙伴要么消除在家中的不准确性，要么最终确定规格。 结果，当代码工作开始时，开发人员将收到工作文档。
最受欢迎的差异：
- 错误的请求格式，承诺接受json，结果证明需要表格数据；
- 请求中要传输的字段名称错误；
- 字段格式错误；
- 字段验证规则未指定或显示不正确；
- 有些领域可能会被完全忘记；
- 缺少或与方法的响应格式的实际描述不同；
- 关于必填字段的错误标记-“星号”可能出现在实际上不是必填字段的地方，反之亦然；
- 通常不会记录对象可能处于的所有状态；
- 对象的预期状态和接收状态之间的差异。 例如，在某些时候，我们希望应用程序处于X状态-实际上，通过API，我们得到Y。
幸福食谱：避免API集成错误
编写与服务集成的规范。 我们花了两天的时间在YAML中开发规范，但是现在我们节省了数十小时的改进和批准。
如果合作伙伴发送了其规格，请在检查清单中进行检查。 在清单中，收集您必须获得答案的问题。 不要依靠经验和记忆，仍然会错过一些东西。
有术语表以避免与您的伴侣混淆。 我们的经验表明，差异甚至可以明显地体现出来。
在获得与合作伙伴的集成管理的原则性批准之前，不要把任务付诸开发。 这个想法很明显，但是它可以帮助我们避免不必要的工作。
打开清单以阐明访问合作伙伴的API的细节：连接详细信息，白名单，SSL证书验证，流量加密要求等。请尽快检查清单，以免在最后阶段出现滑动。
有规范-不要着急立即编写代码。 首先，通过API客户端（例如通过Postman）手动运行该过程。 因此，您将在早期阶段以少量资源发现规范中的错误。 他们会的。