S1E6 为什么 OpenAPI 的设计如此重要？

在 APILetter 的 S1E6，我想和你聊聊 OpenAPI 设计的重要性。 在整个 S1 的文章中，我用了接近 4 篇的篇幅来介绍 OpenAPI 的设计，从一开始介绍为什么要使用 RESTFul ，到 API 的错误码设计理念，辅以批量接口设计的实例，再加上最后这篇重要性的强调，三分之二的比重，意在让你深刻认识到，OpenAPI 的设计至关重要。 为什么 OpenAPI 的设计如此重要？ 在企业内部工作时，常常需要找到平衡质量和速度之间的折衷方案。当项目时间非常紧迫时，往往会牺牲一些质量。但如果项目有足够的时间，就有更高的概率能够设计出一个质量更好、开发者体验更佳的 OpenAPI。 然而，OpenAPI 是一项非常重要的任务，不能马马虎虎。一个坏的设计会让团队持续在 OpenAPI 开发上投入更多的精力。 沟通难度高带来的维护成本增高问题 和企业团队内部使用的 API 不同，OpenAPI 的用户是外部团队，

S1E5 如何设计一个符合 RESTFul 风格的批量操作的 OpenAPI 接口？

许久不见，甚是想念，最近做了不少 RESTFul  API 的设计实践，分享一下最新的经验。 在遵循 RESTFul 风格设计 OpenAPI 时，简单的创建、更新、查询、删除是比较好做的，大家也大多能够想到如何设计对应的接口，无非是用 POST 做创建、GET 做查询、DELETE 做删除、PUT、PATCH 做更新，但设计到批量的操作时，大家往往会有一些困惑，今天我们就来聊聊 RESTFul 下的批量操作。在给出我自己具体的实践之前，先来看看业界的实践。 业界的两种实践 由于 RESTFul 风格定义当中并没有明确说明如何设计批量接口，所以业界上也有不同的批量接口设计的思路，大体可以分为两种： 1. 在网关层面设计批量接口的能力，实现异步转同步：这部分主要是会提供一个单独的请求路径，由开发者将自己的请求打包并发送到这个新的路径，由这个路径上的服务将请求结果发送给具体的服务，并将结果收回，返回给开发者。Google 和

S1E4 到底多少个错误码才是合理的？

在对外开放 OpenAPI 的时候，错误的设计也是一个极为影响开发者开发体验的设计点。今天我们简单聊聊关于错误码和错误处理 为什么需要错误码？ 由于我们不能保证系统可以完全处理用户的请求，因此我们需要通过错误码来告诉开发者发生了不符合预期的情况。不符合预期的情况可能由用户输入错误导致，也可能由内部微服务故障导致。为了建设一个健壮（Robust）的系统，我们需要通过对外暴露一批错误码，帮助开发者更好地处理各种异常情况。 避免错误码数量过少 既然我们的目的是帮助开发者解决异常情况，那么一个合理的答案是：和异常情况匹配的错误码数量是一个好的错误码数量。 如果在某个 API 接口上提供了一个错误码，则意味着我们认为这个接口只会出现一种情况导致的错误。而实际上，很可能会有多种情况导致错误发生。这种情况经常在 OpenAPI 评审过程中被提出来，也是用户在使用 OpenAPI 时常遇到的问题：为什么我找不到这个错误码？对于开发者来说，无论输入何种错误，都会得到相同的错误码，难以定位和解决问题。同一个错误码也意味着你无法提供足够的错误信息来进行排查。例如，常见的 “400 Bad Re

S1E3 开发者文档的三种内容层次：字典、概览和教程

Hi，欢迎收看 APILetter，距离上一次更新，已经过去了三周。天津疫情凶猛，今天我终于又来到了街上。现在正在天津大悦城的星巴克臻选里写这封邮件。 不知道，你有没有关注过开发者文档的信息结构。下图是 Google Docs 的 API 文档： 在菜单中 Google Docs 提供了 Home、Guides、Reference、Samples、Support。你有没有想过，这些内容为什么如何设计？在我看来，这是开发者文档内容的三种层次。 第一层：解决有没有的问题 典型代表：API Reference 绝大多数开放平台也好，To Developer 产品也罢，首先要解决的问题是让开发者知道我有什么样的能力。而最简单、最直接最高效的方式，便是 API Reference。 各大产品在进行对外开放时，首先准备的便是一套 API Reference。在 API

S1E2 衡量 API 设计质量的指标 — TTFC/TTFHW

本期是 API Letter 的第二期，天津下起了小雨，一场秋雨一场寒，我在雨中为你撰写这封 Newsletter。 任何一个开放平台类产品，要解决的问题都是如何在现有的平台能力之上，开放一些能力给到第三方开发者，帮助第三方开发者开发应用，拓展体验，如果我们可以降低开发者在完成开放能力接入所需的时间，我们就可以让开发者有更多的时间去构建属于自己的业务逻辑，拓展平台之上的应用生态和开发者体验。 API 的设计质量、文档质量和错误处理信息的质量可以非常明显的影响到 API 的使用体验。但这些体验却很难通过我们在软件工程领域所使用的各种性能指标来衡量。我们可以通过一些专业的、对于 API 有判断能力的人来完成对于 API 质量的评估和优化的引导，但这件事并不利于持续发展和长期迭代。我们需要一个靠谱的指标，来引导我们持续性的、规模化的进行 API 本身的优化和迭代。 在这个问题上，Slack 给出了自己的答案 —— Time to First Hello World（TTFHW）， API 服务提供商 readme.com 则提出了一个类似的概念 Time to

S1E1 为什么开放平台大多选择了 RESTful 风格？

本期是 API Letter 的第一期，我在天津刚刚入秋的周日晚上，为你撰写这封 Newsletter。 大型互联网平台会提供一些开放平台，并提供一定的开放能力，帮助开发者基于自己的平台进行二次开发，拓展平台之上的应用生态。而在这些开放平台当中，最常见的便是采用 RESTful 风格的开放平台，比如 GitHub、Microsoft、Google、Twitter、StackOverflow。 如果说用一个偷懒的想法，那我们可以得出一个结论 —— RESTful 一定做对了什么，不然不会这么多平台都愿意选择它。 考虑到我们的 Newsletter 是一个面向开发者、To Dev 业务的产品经理的邮件，就不再详细介绍 RESTful 是什么，如果你感兴趣，可以去看看 Fielding R T. Architectural styles and the design of network-based software architectures[M]