Get best of the week

API样式指南，或者不要让用户思考



你好！我叫Lesha Rutskoi，我是Wrike的产品经理。在此之前，他曾在Adform和PandaDoc工作。在过去的五年中，我一直在做与集成和API有关的所有事情。

Wrike是SaaS协作和项目管理产品。我们希望开发人员基于Wrike构建他们的解决方案，为此，我们需要我们的API方便使用。同时，我们在全球设有9个办事处，其中3个是开发办事处。使用会讲不同语言的分布式团队创建一致的API相当困难。他们的决定开始相互矛盾的可能性越来越大。在这种情况下，如果没有一套统一的规则，就无法做到。

如果您还以分布式方式工作并制作自己的API，则样式指南API可以为您提供帮助。我想告诉您它解决了哪些常见问题以及如何使开发人员的生活更轻松。我还将分享在公司中编写和实施自己的API样式指南的经验。

为什么我们需要方便的API？


许多读者可能不得不使用不太方便的API解决问题。是的，这不是很简单，需要更多时间，但是通常您仍然可以解决问题。

那么，为什么要浪费时间和团队精力来改善API？答案很简单：开发人员通常会做出有关产品使用的决定，尤其是在API和集成方面。因此，不仅要考虑用户体验（UX），还要考虑DX-开发人员体验，这一点很重要。

我举一个例子。我曾经在负责所有产品集成的团队中工作。通常在本季度中旬，当我们已经计划好计划时，一位营销人员就说：“ Z建立了一个新市场，并将发布其平台的下一个版本。不久，他们将举办一个很酷的公共活动，在这里我们可以谈论我们的融合与成功！如果我们现在就快速编写此集成，那就太好了。”在这种情况下我们做了什么？如果团队中经验丰富的开发人员可以在三天内制作出最低限度的原型，那么通常在两到三周内，我们就可以使任务达到理想的状态。如果缺少几天，那么API和文档都是一般的。对我们来说，重新制定计划并进行新的整合是毫无意义的-都一样，在截止日期之前没有什么值得的。请记住，您的产品可能处于这种情况下-合作伙伴将根据您开始使用API​​的速度和便捷程度来决定是否与您打交道。

但是几乎没有人愿意设计一个错误的API。为什么每个人都变得与众不同？通常，API是这样开发的。当一家初创公司开始增长并吸引了第一批客户时，其中一个团队确定了端点，并决定将版本转移到URL：

图片

逐渐出现新的客户和新的需求。第二小组的成员包括在工作中，他们认为最好使用自己的媒体类型进行版本控制：

图片

一段时间后，第三小组到达。在一次会议上，他们了解到Stripe将使用主要发布日期对其API进行版本控制。他们决定这样做：

图片

结果是一个API，其中包含三种版本控制方法。所有方法均有效，但工作方式不同。

作为开发人员，使用这样的API对于我来说很不方便。原因不是我不喜欢一种对其他所有人进行版本控制的方法。同时使用几种方法很不方便。您必须编写与API一起使用的代码三次，或使用三个不同的库。这意味着错误的数量将是原来的三倍。

并且有日期和时间。即使使用标准方法，也可以通过不同的方式传输数据：通过服务器的时区，通过GMT，通过客户端的时间（以Unix时间）。客户将需要将所有数据转换为一种格式。

错误消息通常会做不同的事情。例如，像这样：

图片

或像这样：

图片

还有我最喜欢的错误消息-空答案：

图片

好吧，这很经典-答案是200 OK，其中包含JSON和错误说明。

我认为，良好的API中最重要的是一致性。选择哪种版本控制方法都无关紧要，主要的是在整个API中它都是相同的。一个更成功的解决方案是采用其他公司已经采用的流行方法。您的客户很可能已经遇到过这种情况，并且他们有现成的代码或库。无需再考虑，您可以使用现成的工具。

对于拥有分布式团队的大公司而言，创建API的单一方法尤其重要。如果会议室中有十个人创建了一家初创公司，那么每个开发人员都可以简单地敲打邻居，同意或查看代码审查过程中的主要问题。在大公司中，这变得越来越困难。

样式指南API将帮助您解决此类问题。本文档描述了API的设计原理。如果每个人都使用相同的方法，则该API似乎是由一个人开发的，而不是由许多不同的团队开发的。当团队就如何编写代码达成一致时，这种方法很像《代码样式指南》。一个团队中的一个人可以查看另一团队的代码库，并快速了解那里发生的事情。

如何制作自己的API样式指南？


Arnauld Lauret（被称为API Handyman）创建了一个不错的网站-API Stylebook。他编写了一个公开可用的样式指南，各种公司（思科，谷歌，红帽，政府机构和许多其他公司）都将其编入了公共领域。

指南分为网站主题。例如，如果您对版本控制感兴趣，则在“版本控制”选项卡上，您可以找到不同公司如何解决此问题。

从他人的经验中学习！但是完全复制别人的样式指南不是一个好主意。他仍然解决了另一家公司的问题，而不是您的问题。

在样式指南中，您应该添加与公司紧密相关的主题并解决您的问题。也许您有很多移动应用程序，答案的大小对您很重要。然后描述与这方面相关的原理。或者，您与内部团队一致认为，是时候将这种整体变成微服务了，这些微服务将通过Message Broker相互通信。在这种情况下，您需要在API样式指南中包括使用Kafka或其他工具所依据的原则。

样式指南API中还包括什么


此外，样式指南应包括公司所遵循的基本价值和工程方法。

他们会是什么？

  • Write APIs in English. , . - , , . Style Guide, , .
  • API First principle. API : , , frontend-. , API . , , .
  • 使用REST和JSON。如果您想让尽可能多的受众使用您的API或平台，这可能很重要。尽管GraphQL自2017年以来变得越来越流行，但并非所有人都知道这一点。大多数开发人员很可能从未使用过它，这意味着他们将增加沉浸和开发的时间。为什么要创造复杂性？

此外，基本原则可以按主题列出。例如，按照使用REST和JSON的原则，您可以轻松确定应在《指南》中描述哪些主题：

  • 首选具有JSON负载的REST API
    • HTTP请求
    • HTTP状态码
    • 杰森

关于每个主题，您可以提出公司所有团队应遵循的规则：

  • HTTP请求
    • 必须正确使用HTTP方法
    • 自定义HTTP标头应遵循命名约定

我真的很喜欢这种描述需要通过动词MUST，SHOULD或MAY（从RFC 2119借用）来遵循规则的方法。然后，每个阅读《样式指南》的人都会区分强制性规则和建议。

例如，这是在Zalando中的外观：

图片

启动样式指南时要记住的事情


  • . , . , , . , , . API management , . API.
  • . - 15- . rate limiting, .. — , , - .
  • . , OAuth, REST. , , , scopes .
  • . , , .
  • . , . , . . . , .
  • . , , .
  • . , , .. : , «user», , «user», .
  • . , — . , (OpenAPI-, -) . .

API Style Guide?


您已经创建了API样式指南，现在仍然可以实施。这也不容易。我将在我工作过的地方之一分享实现API样式指南的经验。公司结构复杂：数百名工程师，分布在四个开发办公室的数十个分布式团队，同事使用不同的语言。

首先，您需要说服利益相关者。在这里，我们经常谈论各个领域的技术领导者和业务代表。每个人都应该了解我们要解决的问题以及《样式指南》如何提供帮助。在我的示例中，所有利益相关者都知道，良好的API是重要的优势。许多客户都提出了这样的要求，而竞争对手并没有打and睡，而是积极地通过他们的API扩大了机会的范围。

下一步是找到一支可以做到这一点的团队。就我而言，该公司已经有一个独立的团队来支持外部API。她最了解变革的必要性，因为她在工作中经常遇到困难。该团队的成员很高兴参加了该项目。

团队如何实施样式指南API？

  • 她在内部会议和黑客松上谈到了该计划，以便公司中的每个人都可以了解正在讨论的内容。这有助于吸引志趣相投的人，这些人在下一阶段非常有用。
  • 编写了一份样式指南草稿，随后与API倡导者达成了共识（关于他们的观点再进一步一些）。
  • 向团队介绍了该项目。他们去了每个开发办公室，与几乎所有团队进行了交谈，解释了项目的含义并进行了培训。
  • 帮助设计API。许多团队很难在第一次完成指南中的所有操作。帮助和其他说明在这里非常有用，特别是在异常情况下。
  • 进行了审查。确认所有团队都按照《风格指南》行事很重要。

大型公司中的一个团队很难实施如此重大的更改。需要支持。在这里，API冠军们联系在一起-每个方向的架构师和技术人员都将这个想法整合到了他们的团队和部门中。

进行关键更改时，经常会出现不满。在这种情况下，您需要能够使这些人相信更改需求的权限。Tehlids是最合适的人。

API支持者在一个单独的Slack频道中讨论了新出现的问题和建议。立即进行了较小的更改，而较大的更改则需要详细讨论。在这种情况下，发起者提出了一个正式建议：需要解决什么问题，已经存在什么解决方法，它们有什么优点和缺点。然后，我们在办公室外的地方聚集了1-2天，讨论了想法，选择了解决方案并将其修复。然后，我们向团队介绍了我们做出的决定：为什么做出决定以及下一步需要做什么。

此外，API冠军还帮助他们进行了相关领域的评论。团队中的成员首先求助于他们，然后由创建样式指南的团队进行了最终审查。

一段时间后，公司中开始形成一个API社区。它包括经过多个审查周期的人员，弄清楚什么是好的和正确的设计，为什么需要它以及如何进行设计。我们创建了一个大型聊天，每个人都可以问一个问题，API社区的成员帮助解决了这个问题。

您不能仅在工程级别上实施该方法。销售，支持和营销团队还应该了解API涵盖了哪些用户场景，其承载的价值，它与公司战略的关系以及如何正确地将有关其的信息传达给客户。

我们试图将所有这些内容引入公司中大多数团队的加入，包括非工程团队。这也是必要的，以便每个人都了解您何时，在什么情况下以及可以向谁寻求帮助。

自动化


最后一个重要主题是常规过程的自动化。该评论可以作为一个很好的例子。在拥有大量团队的大型公司中，最有可能需要进行大量审查。我不想在基本问题上浪费时间，例如缺少错误描述或错误的ID格式。

一些工具可以帮助您：

  • Zally从Zalando检查，看是否OpenAPI的规范的API风格指南一致。Zally的基本配置检查是否符合Zalando样式指南，但是您可以重新定义并添加自己的规则。
  • Apiary的Dredd检查最终的REST API实现是否符合您的设计，即OpenAPI，Blueprint或RAML规范。

本文是我与Miro的Platform Developers Conference谈话的笔录。您可以在此处找到演讲视频。

我很乐意回答您有关实施API样式指南的问题。如果您分享类似的经验，这也将很酷！

特别感谢Daria Ivanova在撰写本文时所提供的帮助！

More articles:


All Articles