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