在当今这个高度互联的世界中,API 正变得越来越重要,它们渗透到软件领域,以实现新的和改进的创新,从而推动战略和业务举措。
近年来,一种构建和使用 RESTful API 的新方法在行业中迅速普及,微软和 Facebook 处于领先地位。这就是 Graph API。我最近有机会与微软 Graph 的首席 API 架构师 Gareth Jones 坐下来交流,以了解 Graph API 是什么,其开发原因,微软如何制定其 API 开发策略,以及他对 Graph API 这样大型项目版本管理的看法。
什么是 Graph API?
微软 Graph API 是一个单一端点,它将微软云服务数据及其相关的洞察和智能统一在一个单一端点之下。
微软 Graph API 已投入生产一年多,有超过 12 个主要业务组及其各自的子服务连接到 Graph。 
微软 Graph 开发堆栈
来源:https://graph.microsoft.io/en-us/docs
转向 Graph API
微软的 Graph API 已经存在了一年多。Gareth 解释说,转向 Graph 架构主要是为了缓解客户问题。众所周知,微软是一个庞大的组织,旗下拥有各种基于云的服务,每个服务都有自己独特的 API。因此,最终用户处理这么多 API 变得有些困难。每个服务都有不同的调用方式、不同的响应数据包和身份验证机制。因此,需要花费大量时间和资源来学习和集成这些服务。
虽然微软确实尝试在内部标准化其 REST API 设计标准,但它仍然没有解决访问各种微软资源需要多次身份验证的问题。由于微软产品的互联特性,将所有这些资源整合在一起似乎是最好的前进方向。将其转化为各种服务和资源的一个互联图,允许用户在服务之间无缝跳转,而无需不断学习如何集成它们,或重新申请 API 令牌。因此,Graph API 应运而生。
“将我们的 API 转化为一个互联的 Graph,使用户能够非常无缝地在服务之间跳转。我们很快就对这种理念感到兴奋,即不仅将它们聚合到单一端点下,而且实际将服务相互连接,并将它们链接到这个信息图中,从而可以轻松地进行遍历。”
Graph API 不会暴露新的云服务,但提供了连接现有服务的新方法。正如 Gareth 所解释的,Graph 使在不同实体和对象之间导航变得更容易,从而与来自不同服务的数据形成有意义的关系。
Graph 对客户意味着什么
Gareth 说,起初,人们对 Graph API 的概念既着迷又有些担忧,因为他们还没有在实践中看到它。节省往返时间、学习和集成各种服务的能力是 API 首批客户的兴奋之源。然而,在实际看到实施并有机会尝试之前,人们可以理解地感到担忧。
用户最初提出的一个担忧是,在他们和他们想要与之通信的服务之间增加了一个额外的“层跳”。这可能对性能和加载时间产生负面影响。然而,在实践中发现,这种代理调用和路由可以非常非常快速地完成。这在几毫秒内发生,这些担忧很快就消除了。
“我们很快就能向人们证明,与实际在各种服务之间进行多次往返并花费大量资源学习新的 API 调用相比,这些担忧根本不是什么大问题。”
Gareth 说,在 API 领域工作最棒的一点,是看到各种用户如何以创造性的方式集成 API 时带来的惊喜和快乐。Graph 的一个令 Gareth 感到惊讶的方面是,教育部门对 Graph 的热情程度。大学和 K-12(幼儿园到高中)领域从 Graph 中受益匪浅,并获得了巨大的采用率,超出了通常的预期。
构建 API 的方法
微软有多个团队负责多个 API,因此没有集中的 API 开发政策。在这样一个庞大的组织中,我渴望了解他们采用哪种方法来构建 API——设计优先还是代码优先?
Gareth 说,从文化上讲,微软赋予各个团队灵活性,让他们可以采用任何他们认为适合其开发工作流程的方法。他举了 OneDrive 团队遵循的“文档优先”方法为例,这是“设计优先”的一个极端例子。在设计优先方法中,重点是在编写代码之前首先设计各个 API。设计是一种人类和机器可读的参考文档,以 OpenAPI 规范或其他描述语言编写,粒度细致到代码级别。在文档优先方法中,开发过程从场景文档开始,因为高层次、以客户为中心的用例场景是构建出色 API 的关键。
“‘设计优先’的支持者倾向于讨论单个 API 的设计,深入到单个 API 代码的级别。OneDrive 团队真正观察到的是,正是那些总体场景造就了出色的 API。客户实际上是试图通过一系列 API 完成一项工作,而场景文档则说明了如何最好地完成这些特定任务。然后,他们会在该文档中添加注释,以便为每个 API 生成一个 API 描述语言文档。他们的 API 描述语言源自他们的文档,而不是反过来。”
然而,正如 Gareth 早先指出的那样,这种方法并非集中化的,只有某些团队遵循它。Gareth 认为,设计优先或文档优先方法对于 API 开发过程来说非常棒,因为 API 开发过程通常不是一个敏捷过程,因为在生产环境中发布的 API 破坏性更改的数量是有限的,并且会在持续一段时间内发生。话虽如此,这种方法在开发 Graph API 方面也存在局限性,因为 API 描述语言尚未完全发展到可以设计 Graph API 的程度。虽然 Swagger 2.0 在描述资源和操作方面表现出色,但 Graph 的互联性质使其无法完全用 Swagger 2.0 进行描述。微软对 OAS/Swagger 3.0 的新增功能感到非常兴奋,这些功能将使 Graph 的描述变得容易得多。
归根结底,适应不同的开发方法需要特定的技能水平,这最终取决于团队的优势和成熟度。这种使用不同方法的精确灵活性也是 SwaggerHub(一个集成化的 Swagger 开发平台)的核心原则。SwaggerHub 允许组织和团队遵循最适合其技能集的工作流程,利用 API 生命周期的各个方面,无论是设计、文档还是部署。
版本策略
即使有如此多的服务统一在 Graph 下,并拥有庞大的用户群,微软仍设法保持在版本 1。
Gareth 解释说,Graph API 有严格的版本控制策略,有助于防止破坏性更改,同时允许各个单元添加无限量的非破坏性更改。这一策略已被证明非常健壮,因此团队无需更新整个版本。将来,肯定会有 API 的重大更新,这将需要发布新版本的 Graph API。Gareth 将与各个团队合作构建 Graph 比作“同步舞蹈”。Gareth 对版本控制的建议是始终将客户放在心上。当新版本发布时,Gareth 表示 Graph API 的 V1 版本仍将长期存在,以便客户可以逐渐过渡到 V2。
“API 服务以及我们与 API 服务签订的合同都关乎信任。开发者同理心对我们来说非常重要。我们在微软遵循的座右铭是为我们的开发者构建一款出色的产品,并尽一切努力赢得并维持开发者的信任。”
Gareth 认为,有效的沟通是与最终客户保持良好、值得信赖关系的关键。
“如果你有正确的遥测系统,那么你就知道哪些客户仍在使用你的旧 API。你可以联系这些客户,与他们进行良好的对话,了解你能做些什么来帮助他们向前发展,以及你如何才能在适当的时间表上进行升级并共同努力。”
结语
微软的 Graph API 使用通用模式定义语言 (CSDL) 。Gareth 表示他期待 OpenAPI 规范 (OAS) 3.0,因为该规范下一版本的新功能将使其能够使用该规范设计 Graph API。有趣的是,Graph API 将如何演进以整合 OAS 3.0,以及 Gareth 明年能告诉我们哪些新的创新和成功案例。
感谢您的阅读!正在寻找更多 API 资源?订阅 Swagger 新闻简报。每月接收包含我们最棒的 API 文章、培训、教程等内容的电子邮件。 订阅