Season 1: 杂文

加更: 聊聊 APILetter 的新计划

白宦成

白宦成

— 4 min read
加更: 聊聊 APILetter 的新计划
Photo by Glenn Carstens-Peters / Unsplash

Hi，你好，

APILetter 从创刊号，到 S1E6，经历了一年的时间。

虽然在定更新节奏时，我就考虑到自己拖更的可能性，但确实没想到我拖更这么严重，在 2022 年，一口气更新了 3 篇，然后就是长达半年的拖更。不过，总算是把第六篇写完，算是给 Season 1 做个了结。

过去

APILetter 的出现，是源自我在研究 RESTFul 架构时发现的问题：国内有太多解释什么是 RESTFul 规范的文章，但你点进去看，篇篇都是复制粘贴。

而 API 是开发者生态中非常重要的一环，它不应该被草率的对待，开发者们值得用上更好的 API。既然没有人写关于 API 的严肃内容，那就从我开始吧。刚好我在研究相关的内容，那就写一些 API 到底应该是什么样的。

也正是抱着这个想法，我开始了一篇篇的创作，从为什么是 RESTful API，到如何设计一个符合 RESTFul 风格规范的批量操作 OpenAPI；有务实的内容，也有务虚的内容。但不变的是希望让大家明白如何设计一个更好的面向开发者的 API。

但，Season 1 的内容也是杂乱无章的，聊过 RESTFul、聊过 API 文档、聊过 API 指标、聊过 API 报错，这样杂乱且没有主线的内容，作为博客来说，还算可以接受，但作为 Newsletter，可能就显得过于随意。因此，在 Season 2 开始，内容也会开始面向主题，我也会更早的设计不同的 Season 要讨论的话题，以便于让你可以有更好的阅读体验。

未来

在写第一篇邮件通讯时，我就注册了域名 APILetter.com，因为我知道这件事我应该会做很久，所以搞一个独立的站点是必然的事情，也是符合我习惯的事情 —— 每搞一个事情，就要给它一个独立的品牌。

而在刚开始写第一封邮件时，我是没有勇气使用独立的站点的，我总担心自己写完第一封就写不下去了。那搞一个独立的站点不过是浪费时间。所以我选择从竹白开始我的写作之旅。一年过去了，获得了还算不错的效果（至少比我想象中的要好一些）。

不论过程是否艰辛，总归我是完成了自己对自己的承诺，至少写完了一个 Season 的内容。

而 APILetter 完成了第一阶段的产出后，下一个阶段，我希望用更加品牌化的方式来运行这个项目，便启用了 APILetter.com 的域名），并搭建了 Ghost 来托管这个项目。

换到 Ghost，除了域名独立、程序独立、数据独立，相应的，自然也有一些好处 —— 比如可以 RSS 订阅了。如果你希望通过 RSS 的方式来订阅 APIletter， 也可以直接访问 https://www.apiletter.com/rss/ 来订阅。

Season 2：指标

在 Season 1 中，我花费了不少的篇幅来讲 OpenAPI 的设计问题。在 Season 2 ，我想专注于 OpenAPI、开发者体验中的指标问题，从企业和个人制定目标开始，到具体到某一个具体的 OpenAPI 指标评定。

目前预计会包含的内容：API 自身的指标定义、API 相关业务的指标定义、开发者体验中的一些指标定义。

除了这些指标，你还关注哪些指标？欢迎回复邮件告诉我。

总结

总之，APILetter 在新的一季里，我会尽量以更好的内容组织方式、更高的频率（但暂时承诺还是每月一封哈），来给大家分享我自己关于 API、关于开发者体验，以及一切与开发者有关的内容，希望可以帮到你。

如果你身边有对于开发者关系感兴趣或从事相关内容的朋友，欢迎你将 APILetter 介绍给他，帮助我获得更多的读者，以及，持续的写下去🥰。

祝好，

白宦成

Read more

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

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

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

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

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

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

By 白宦成
S1E4 到底多少个错误码才是合理的？

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

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

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

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

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

By 白宦成