翻译自 API Design Guide - Compatibility

本章提供了有关版本控制部分中给出的破坏和保持兼容性修改的详细说明。

翻译自 API Design Guide - Versioning

这一章是网络 API 的版本控制指南。因为一个 API 服务 可以（may） 提供多个 API 接口，API 版本策略应用在 API 接口上而不是 API 服务。为了方便，下面的 API 表示 API 接口。

翻译自 API Design Guide - Using proto3

这一章讨论在 API 设计中如何使用 Protocol Buffer。为了简化开发体验并提高运行效率，gPRC API 应该（should） 在 API 定义时使用 Protocol Buffers 第 3 版（proto3）。

翻译自 API Design Guide - Documentation

这一章是为 API 添加内部文档的指南。大部分 API 有概述、教程和更高级别的参考文档（此指南不讨论）。API 名、资源名和方法名的信息请查看命名约定。

翻译自 API Design Guide - Design Patterns

空响应体

标准的 Delete 方法 必须（must） 返回 google.protobuf.Empty 来实现全局一致性。它还可以防止客户端依赖于在重试期间不可用的附加元数据。因为随着时间推移对于自定义方法， 对于自定义方法，它们 必须（must） 具有自己的 XxxResponse 消息，即使它们是空的，因为功能很可能随着时间的推移而增加，并且需要返回附加数据。

将字段首字母改为小写或添加 json:"-" 标签能够在 json.Marshal() 时忽略指定字段，但此文章想讨论的是在不修改原 struct 结构的前提下过忽略部分字段的方法。

为什么会有这种需求呢？如果要转为 json 的 struct 定义在依赖包中或有其他地方需要输出这些字段，这时就不能修改原 struct。

翻译自 API Design Guide - Naming Conventions

为了在长期和大量使用的 API 中提供统一的开发体验，API 中的所有名字 应该（should） :

• 简单
• 直观
• 一致

此文章讨论了接口、资源、集合、方法和消息的名字。

翻译自 API Design Guide - Errors

本章简单介绍 Google API 的错误模型以及开发人员如何正确生成和处理错误的一般指导。

Google API 使用了简单的协议无关的错误模型，这允许我们在不同 API，不同协议（例如 gRPC 或 HTTP），不同的错误上下文（如同步、批量处理、工作流错误）中提供相同的使用体验。

翻译自 API Design Guide - Standard Fields

本节介绍了在需要类似概念时应使用的一组标准消息字段定义，这将确保相同的概念在不同的 API 中具有相同的名称和语义。

翻译自 API Design Guide - Custom Methods

此篇文章讨论如何在 API 设计中使用自定义方法。

自定义方法指五个标准方法之外的 API 方法。应该（should） 只有当标准方法不能完成需要的功能时才使用自定义方法。一般情况下，API 设计者 应该（should） 在可行的情况下选择标准方法。标准方法有更简洁和明确定义的语义并且被大多数开发者熟知，所以它们更易于使用并且不易出错。另一个优势是 API 平台对标准方法的支持更好，比如计费、错误处理、日志和监控。

自定义方法可以被关联到资源、集合或服务。它 可以（may） 接收任意请求并返回任意响应，并且也可以支持流式请求与响应。