OpenAPI开放平台产品设计及运营

OpenAPI开放平台几乎是中大型技术服务企业的标配，客户通过OpenAPI将企业服务快速集成到自身信息系统中，供应商通过OpenAPI向企业提供服务，合作伙伴通过OpenAPI与企业高效协作。本文将详尽地阐述Open API开放平台的产品设计和运营，并分享对于OpenAPI相关的企业治理问题的一些思考。

OpenAP平台产品简介

1. OpenAPI平台的起源

互联网出现前，信息系统是由ISV（Independent Software Vendor）部署在企业自身的机房里的，这些系统只能解决企业内部特定办公任务场景下的信息管理质量和效率问题，例如Office三件套、Oracle财务软件，企业间的业务往来还得靠线下的合同、单据、票据，例如通过采购合同下采购单。

互联网出现后，开始出现一些间简单的网络传输协议，如FTP文件传输协议、HTTP数据传输协议，在全球供应链和贸易领域中，传统线下业务单据开始被EDI(Electronic Data Interchange)技术所取代，标准委员会制定出一些电子单据的格式规范，例如X12标准的采购订单（850），企业只需将业务单据以标准格式存储、传输，便可与全球采用EDI技术的贸易伙伴高效开展业务，企业间的信息交换进入电子化时代。这个时代开始出现最早期的OpenAPI平台，例如 中国电子口岸，通过提交申请表，企业即可对接海关的EDI接口，向海关提交电子化的报关表、通关申请单、通关货物清单等。

随着企业信息化技术、互联网技术、网关技术的普及，信息存储、交换的粒度和环境出现了颠覆性变化，此前企业间交换信息一般以单据为粒度，但现在企业间交换信息可以到细化到任意粒度，例如零售企业只将一个SKU的信息下发到物流服务商的仓库。此前企业间信息一般存储到Oracle数据库中，但现在企业间信息存储的方式多种多样，并且单位信息的存储成本近乎无限低。因此逐渐发展出基于互联网HTTP协议的信息交换技术，简称API接口。相比于EDI技术，API接口的功能和信息格式可以按需自由定义，没有任何约束，企业间交换信息更加自由。

随着云计算技术、SaaS服务技术的发展，市面上逐渐出现一批以撮合交易为主营业务的特大型的平台型企业（例如京东购物平台），上下游以这些企业为中心开展商业活动，这些企业为了提升自身与上下游企业的信息交换效率，制定了一些标准的安全规范，针对业务定义了一些标准功能的API（如库存同步、订单拉取、轨迹回传等），并将这些API文档和安全规范公开展示出来，由此形成了目前市场上的OpenAPI开放平台，例如京东JOS开放平台。

2. OpenAPI平台的核心业务流程

OpenAPI开放平台也是典型的平台型产品，平台的业务流程是围绕API的供给和消费来进行的：

• 供给方：设计并开发API→编写配套使用文档→发布API到平台→API运维答疑
• 消费方：查找特定功能的API→申请API使用权限→使用API→问题咨询→API运行监控
• 平台方：审核API发布→审核API使用资质→排查API运行问题→迭代优化API

可以直接体验淘宝开放平台，对于开放平台会有直观的认知。

3. OpenAPI平台的类型

不同行业、类型的企业对于OpenAPI平台的诉求不一致，主要分为以下几种：

4. 本文的适用范围

本文是针对大型企业建设「业务渠道」类的OpenAPI平台而写的，其中大部分方法同样也适用于其他类型的OpenAPI平台的建设。大型企业建设OpenAPI平台时的工作除了建设标准技术对接模式和标准API等基础产品能力外，还需要面临一系列由于客制化工作带来的产品和运营上的挑战，例如KA客户指定使用的技术模式与平台标准不一致、大型项目里需要多个研发团队协作完成系统开发和对接，另外还要解决 API治理、服务机制建设等等难题。

一、产品设计

具体的产品设计方法论可以看如何做好B端产品规划？这“一揽子工具”帮到你，本文介绍的是业务渠道型的OpenAPI平台的建设，因此后文所有产品设计和运营也都围绕这类OpenAPI平台来展开。

1. 产品定位

【为谁解决什么问题】业务渠道型的OpenAPI平台为企业系统实施人员解决客户导入过程中的的**系统对接效率**问题。在缺少OpenAPI平台时，系统实施人员把每个客户的导入当做一个项目来做，拉着双方的产研同学沟通对接方案，典型的工作流是 方案沟通→开发→测试联调→上线。在拥有OpenAPI平台后，企业内部的标准API能力建设过程与客户导入过程相分离，产研将标准API发布在平台上，编写配套文档，客户可通过平台实现自助化的对接，大大提升系统对接效率。

【市面上的竞品】顺丰开放平台、菜鸟开放平台

【用户角色、核心用户任务、关键产品能力】

2. 架构设计

OpenAPI平台在产品架构上与一般的平台型产品没有区别，就是三个端：

1. 公网客户端（消费者）：给客户做业务接入使用的端，相当于淘宝APP。特别的，客户端由分为前台和控制台两个部分，前台用以展示API和文档信息，后台用以做应用创建、资质认证等实际的操作。
2. 内网管理端（生产者）：给业务线产研发布API的端，相当于淘宝商家后台。特别的，管理端由分为前台和控制台两个部分，前台用以展示平台规范、使用手册等信息，后台用以做API发布、运维监控等实际的操作。
3. 内网运营端（平台运营）：给平台运营同学做平台内容管理、信息审核、运营监控的端，相当于淘小二工作台。

以上三个端都是具有人机交互界面的端，这三个端为用户的接入体验和效率负责，实际上还有一大块能力不易被感知，那就是API网关能力。API网关对API运行的安全和稳定负责，是双方系统数据交互的最最基础的保障。在一次次的API调用过程中，API网关负责识别用户身份、加解密数据、拦截异常流量，从而保障内部系统的安全，为客户提供性能稳定的API服务。API网关的建设由于技术性强一般由研发主导，而三端的建设则由产品主导。最简版的API网关可以只建设「API元数据、应用AppKey管理、标准签名、OAuth2.0鉴权能力，随着平台用户量的增加和治理工作的开展，需要提供更多样的安全策略供用户选择、健全基本的网关安全能力，保障双方系统安全。

可以在1.1的「用户角色→核心任务→关键产品能力」的基础上，采用文章从需求到功能，B端产品设计四步法中的方法归纳总结得出每个端的核心功能以及三端共用的底层能力，最终得出以下架构图：

3. 能力清单

建议阅读从需求到功能，B端产品设计四步法，基本原理就是：

1. 拆需求：一个最小的子需求，应有3个要素组成，XX用户在XX场景下的XX需求；
2. 拆事件：一个需求的结果 = 事件1+事件2+事件3+……，其中，事件X=用户XX通过XX做XX；
3. 事件模块化聚合：用户通过XX做，这里面通过“XX”这个对象，就是产品的功能；这个步骤的主要作用，就是将离散的功能点所需要的承载体，聚类聚合；

通过这个方法，再根据1.1的用户角色→核心任务→关键产品能力得出能力清单，在此不再贴录能力清单。

4. 能力地图

5. 版本规划

MVP版本包括的功能集实际非常简单，只要保障「API发布→API展示→API使用」的主链路能通即可，其余API文档、日志等功能都可以有替代方案，例如通过线下文档替代在线文档、通过微信答疑代替工单能力。但研发侧还是要直接按产品侧的架构来搭建系统，一步到位，这样才能在不变更系统架构的情况下快速迭代增加功能。建议按以下进行最初几个版本的迭代：

1. 版本1：按产品架构设计，搭建系统框架，在各端上完整展示菜单，菜单点击后均显示同一个页面，页面提示“功能正在建设中”，最终的产品效果相当于一个空壳系统。
2. 版本2：MVP，研发将核心功能逻辑的架构设计好，并实现核心功能的最简版，相关核心功能有「产研发布API→公网客户端展示API→客户申请资质认证→平台运营审批资质→客户申请API使用权限→平台运营审批API使用申请→API调用时签名校验」，以「发布API」功能为例，最简版可以做成表单填写，填写完成即发布完成，先不建设API状态机、API文档编写这些复杂的功能。这个版本上线后，就可以提供给产研和客户使用。
3. 版本3：建设对接周期统计能力和体验评价能力，以体验和效率为导向建设平台。建设完整的文档编写和展示能力，在过去的运营经验中，最大成本源自于线下文档的版本变更，每个人手里拿到的文档版本不一致，导致各种返工。并且专门的API文档能力能大大提升客户学习使用API的效率。
4. 版本4：围绕客户的接入效率，建设完整的API导航、API调试工具、日志工具等能力。
5. 版本5：围绕客户的接入体验，进一步优化各类工具的使用体验。

本章节只讲解产品功能建设上的版本规划，实际上各个版本还要配套运营动作，才能使平台最终变得可用、好用。关于平台的运营请看第二章。

二、产品运营篇

典型的平台型产品 = 平台交易工具 + 配套平台流程规范 + 平台运营治理，第一章已经讲解平台交易工具的建设，本章节着重讲解平台流程规范的建设和日常运营治理。

1. 平台冷启动

当产品MVP版本建设好后，理论上可以投产使用，但由于功能非常简陋、不健全，实际是无法交付给运营的。此时，产品需要完成冷启动工作：

1. 编写客户端、管理端的使用手册（线下版）；
2. 寻找合作部门，讲解平台的建设目标、使用方法，与他们在业务维度共建一套完整的API；
3. 寻找试点客户，引导客户使用这些API，并解答客户疑问，根据客户问题不断优化文档；
4. 做好数据采集，平台的核心运营指标是客户对接的体验和效率，未来平台的持续建设也是围绕这两个指标进行的，因此在平台上线运营之初就应该具备这两个指标的采集能力，具体的指标运营可以看章节2.3；

在冷启动过程中，实际产品承担了运营和技术支持的职能，这样产品可以深入一线了解客户关心的问题、深入理解好的使用手册应该包含的内容，为后期平台的体验优化、规范制定提供实战经验。通常平台冷启动需要持续3个月时间，这期间平台功能、平台上的API、配套手册均已经过多次迭代，客户根据手册基本能自助完成对接。

当平台功能流程相对完整、稳定后，就可以将平台的答疑工作交付给技术支持团队，产品可以抽身出来扩大平台的服务范围，从服务一个业务线扩展到多个业务线。为了将这个业务线的最佳实践快速复制到多个条线，一定需要将一些做法标准化，这就涉及到平台流程规范的建设。

2. 平台流程规范的建设

流程规范一方面是成功经验的萃取，一方面是提升平台相关角色在各种各样场景下的协作效率，笔者根据业务流程阶段，将平台流程规范分为五大部分：

这些流程规范需要经过各部门主要负责人、架构师评审后，才能得到落地，否则内部产研会挑战平台侧制定的标准，特别是有些标准比较苛刻。当平台侧推动各方按流程规范来解决日常问题，基本验证流程规范的可落地性和合理性之后（事实上中间要经过多次修订），就可以考虑将流程固化为平台的功能流程，将规范固化为平台的校验项，使得平台用户自然而然就会遵守流程规范。

3. 平台常态化运营和治理

3.1 客户的对接体验和效率

OpenAPI开放平台的北极星指标的客户对接体验和对接周期。在产品的MVP版本，就应该建设这两个指标的统计能力，这两个指标的统计口径可以因具体的业务而异，一种可供参考的指标口径是：

• 对接体验：客户开发完毕后，需要进行对接体验评分，评分后才可上线应用。以这个环节用户评分的平均分为最终得分。
• 对接周期：每个客户的对接周期 = 客户产生第一笔订单的时间 – 客户注册账号的时间，最终以所有客户对接周期的平均数作为平台的对接周期。

实际上，平台运营过程中不可能只看这两个指标的最终数值，而是要找到影响这两个指标的因素，逐个环节做优化，一种可能的拆解如下：

• 对接体验 = 平台工具使用体验 + API使用体验 + 客户答疑体验
• 对接周期 = 注册账号时长 + API选用时长 + API使用方法学习时长 + API调用代码开发时长

如此围绕北极星指标，就有大量的治理工作要做：

• 平台工单治理：针对工单中高频出现的问题，要么通过平台优化彻底消灭问题，要么通过工具流程的优化缩短问题解决的时长，最终应该达到降低平均每个客户提交的工单数量的效果。
• 平台文档治理：为客户提供文档评价功能，针对客户反馈的平台不详细的问题，定期给文档编写人发文档优化工单，持续提升文档质量。
• 平台API治理：对标行业，持续优化API分类、API名称，避免出现同样功能的API，优化检索排名逻辑，最终提升客户查找API的效率；针对高频出现未知问题的API、字段含义难以理解反复被咨询的API，推动API的重塑，用新的API替换旧API，最终提升客户使用API的效率。

3.2 系统的安全和稳定

事实上，除了在客户导入环节进行提效外，客户业务开展过程中，为客户提供持续稳定的系统服务也非常重要。客户订单无法下发、接收不到订单信息回传将会给客户直接带来经济损失，特别的，一些企业对于API的时延也非常敏感，过高的时延将直接让客户感觉到系统卡顿，影响系统操作体验。因此，平台需要在两个层面持续做好监控，及时发出告警：

• 客户系统和内部业务系统的连通性：客户的网络配置变更或者内部系统部署问题，都会导致数据传输通道中断；
• API在业务层面的可用性：有些情况下，内部系统上线出现故障，会导致特定客户群体的服务受到影响，而内部系统自身却感知不到，因为这部分客户群里的单量占总单量比例太小了；

一种可能的监控告警方案是：

• 针对客户系统，如果系统多次重连都无法连接上客户系统，则直接向客户的研发、销售支持团队、技术支持团队发送告警。
• 针对内部系统，在平台上发布API后，自动为API创建一个监控看板，看板中包括TP99、可用率；当发生业务系统不可联通或在业务层面上不可用时，影响这个API的可用率；业务系统的研发可以在平台上配置这个API对应的告警规则，在可用率下降到下限或TP99超过上限时，系统向API的产品、研发负责人发出告警。

这里特别要注意的一点是，尽量将平台的监控告警和研发日常系统监控告警集成到同一平台，这样研发会更愿意配置告警、关注告警。另一方面，一旦告警发出，需要有恰当的流程机制来解决问题，通常需要平台与IT运维质量团队共同商议流程机制，保障流程机制能落地；一旦告警转换问客户提交的故障单，还会涉及扣减研发团队质量分，影响研发团队绩效。

除了系统稳定性，系统安全性也非常重要，业务越权或数据泄露也会对公司运营造成重大影响。通过三方面措施来防止此类情况发生：

1. 三层鉴权：API使用鉴权、平台的OAuth鉴权、系统的业务鉴权。API使用鉴权主要是客户系统调用某个API时，API网关识别客户系统是否有调用这个API的权限。OAuth鉴权主要是API网关识别当前appKey是否能获取某个账号内的数据。业务鉴权主要是识别这个账号能获取哪些业务数据，例如在电商平台场景下，账号通常与店铺绑定，业务系统需要识别此次请求的数据所属的店铺与账号所属店铺是否一致。API使用鉴权、平台的OAuth鉴权由平台功能来保障，系统的业务鉴权则是在每个接口发布上线前，强制评审接口对应的代码，检查是否有对应的业务鉴权。
2. 安全测试：邀请安全部对于平台上的接口进行攻击测试，如果发现漏洞，则发送安全工单，要求责任团队限期整改。
3. 异常识别：当系统识别到某个客户系统的调用量成倍增加时，应该向平台运营发出告警，人工排查该客户系统是否存在攻击行为，如果确实存在攻击，则应进行系统限流，然后与客户沟通整改。

3.3 流程规范的持续建设

平台在「0-1大规模能力建设 + 平台专项治理」这两个阶段，实际会投入大量人力，在平台功能和业务稳定后，必然会面临成本问题，能否以一个比较低的成本来持续运营平台？经过笔者的实践验证，是可以做到的。平台的运营成本来自于三方面：

1. 内部员工的教育成本：为了保障平台的高效易用，产研需要按照一定标准建设、维护API，平台需要按照规范审核这些API和配套文档，同时一线的销售、系统实施需要学习使用平台，这样他们才能更好的服务客户。企业人员更替频繁，平台需要不断给新的同事讲解平台标准和使用方法，带来了不小的运营成本。笔者的经验是，制作一个内部的门户网站，展示平台期望的各个用户角色需要完成的关键任务，并总结精良的使用手册和实践案例，配以培训视频；将平台的流程规范全部固化到系统，让系统校验代替人工审核，大幅减少审核工作。
2. 外部客户的服务成本：一方面，客户的各类问题层出不穷，但实际绝大部分不是平台工具的问题，而是API的问题，这些问题应该思考如果通过技术支持团队分流到对应的产研团队；另外一方面，有些客户的研发水平比较低，平台制作了一部分Demo供客户参考，客户照葫芦画瓢，平台无需再向客户解释各类技术名词概念。
3. 平台的稳定性治理：为了保障平台技术服务的安全稳定，需要投入一定的研发人力做定期巡检，一种比较好的方式是形成一个定期OpsReview的文档模版，将文档中需要的数据看板全部线上化，把巡检的模式固定下来，这样每次巡检的成本大概可以控制在两三个小时。

实际上，所有成本的降低都指向了流程规范的持续建设，当问题发生时知道怎么处理，日常工作事项可以模板化，不需要花太多精力。

三、一些思考

Q1：开放平台和平台上的API是由一个部门来建设比较好，还是分开比较好？

A1：取决于平台承载的业务范围的大小。一方面，为了服务好客户，API开发部门通常需要掌握OpenAPI相关的设计标准、运营运维工作、客户服务流程，如果API开发部门和开放平台是两个独立的部门，那势必会带来沟通和培训成本。另一方面，一个团队的知识领域是有限的，如果平台承载的业务多种多样，那几乎不可能由一个团队来完成所有业务的API的设计。因此，企业业务相对单一时，API和平台应该由同一个部门来建设；企业业务多种多样时，势必会出现多个API建设部门和独立的平台建设部门。

Q2：作为一个大企业，是所有业务共用一个OpenAPI平台好，还是每个业务各自建一个开放平台好？

A2：需要从两个维度来考虑这个问题，一是各业务的属性的相似度，业务属性差异比较大的业务就不适合共用OpenAPI平台，例如阿里的云计算业务和电商业务显然不适合共用一套开放平台，因为二者的业务流程完全不同；二是组织架构的设定，为了服务好客户，平台需要组织各业务线的系统实施、业务运营、产品研发、技术支持等部门共同服务客户，平台能承载的业务服务范围，取决于平台能统筹的业务部门范围，例如京东零售的JOS平台无法统筹京东科技相关部门，因此二者的开放平台最好分开建。

Q3：如果一项数据涉及客户隐私，容易带来数据安全问题，但业务侧期望开放此类数据供商家做经营，如何选择？

A3：企业的合规安全运营是数据开放的底线，如果数据泄露不会给企业经营运营带来根本性的损害，并且法律并未命令禁止对外提供此类数据，那么就应该开放此类数据以支持业务发展，并对数据使用方做好监管，限制数据使用量。

Q4：OpenAPI平台是一个平台型产品吗？平台交易双方主体是谁？

A4：虽然叫OpenAPI平台，但严格意义上说，OpenAPI平台的工具属性大于平台属性。如果说平台上的商品是API的话，平台侧的工作非是提升客户需求和业务线API之间匹配的效率。实际上客户需要的API直接由客户要对接的业务线决定，平台的工作是将客户的需求传递给业务线，并督促业务线按照一定的标准向客户交付API。因此平台是提供了一个组织多个角色共同服务客户的协作工具，核心价值是提升客户消费API过程中的体验和效率。OpenAPI平台的平台属性体现在两方面，一是通过平台将API的供需双方连接起来，二是平台其承担了双方对接过程中规范制定和监督执行的职能。