函数API设计笔记

API project

https://github.com/googleapis/googleapis
https://github.com/envoyproxy/data-plane-api
https://github.com/istio/api
为了统一检索和规范 API，可以内部建立一个统一的 （如叫bapis） 仓库，整合所有对内对外 API。

• API 仓库，方便跨部门协作。
• 统一做版本管理，基于 git 控制。
• 规范化检查，API lint。
• API design review，变更 diff。
• 权限管理，目录 OWNERS。

API Compatibility

向后兼容(非破坏性)的修改

• 给 API 服务定义添加 API 接口
  从协议的角度来看，这始终是安全的。

• 给请求消息添加字段
  只要客户端在新版和旧版中对该字段的处理不保持一致，添加请求字段就是兼容的。

• 给响应消息添加字段
  在不改变其他响应字段的行为的前提下，非资源（例如，ListBooksResponse）的响应消息可以扩展而不必破坏客户端的兼容性。即使会引入冗余，先前在响应中填充的任何字段应继续使用相同的语义填充。

向后不兼容(破坏性)的修改

• 删除或重命名服务，字段，方法或枚举值
  从根本上说，如果客户端代码可以引用某些东西，那么删除或重命名它都是不兼容的变化，这时必须修改 major 版本号。

• 修改字段的类型
  即使新类型是传输格式兼容的，这也可能会导致客户端库生成的代码发生变化，因此必须增加major 版本号。 对于编译型静态语言来说，会容易引入编译错误。

• 修改现有请求的可见行为
  客户端通常依赖于 API 行为和语义，即使这样的行为没有被明确支持或记录。 因此，在大多数情况下，修改 API 数据的行为或语义将被消费者视为是破坏性的。如果行为没有加密隐藏，您应该假设用户已经发现它，并将依赖于它。

• 给资源消息添加 读取/写入 字段

API Name Conventions

包名为应用的标识(APP_ID)，用于生成 gRPC 请求路径，或者 proto 之间进行引用 Message。文件中声明的包名称应该与产品和服务名称保持一致。带有版本的 API 的软件包名称必须以此版本结尾。

• my.package.v1，为 API 目录，定义service相关接口，用于提供业务使用。

// RequestURL:

/<package_name>.<version>.<service_name>/{method}
package <package_name>.<version>;

API Errors

使用一小组标准错误配合大量资源

• 例如，服务器没有定义不同类型的“找不到”错误，而是使用一个标准 google.rpc.Code.NOT_FOUND 错误代码并告诉客户端找不到哪个特定资源。状态空间变小降低了文档的复杂性，在客户端库中提供了更好的惯用映射，并降低了客户端的逻辑复杂性，同时不限制是否包含可操作信息(/google/rpc/error_details)。
• 错误传播
  如果您的 API 服务依赖于其他服务，则不应盲目地将这些服务的错误传播到您的客户端。在翻译错误时，我们建议执行以下操作：
• 隐藏实现详细信息和机密信息。
• 调整负责该错误的一方。例如，从另一个服务接收 INVALID_ARGUMENT 错误的服务器应该将 INTERNAL 传播给它自己的调用者。

• 全局错误码
  全局错误码，是松散、易被破坏契约的，基于我们上述讨论的，在每个服务传播错误的时候，做一次翻译，这样保证每个服务 + 错误枚举，应该是唯一的，而且在 proto 定义中是可以写出来文档的。