翻译自 API Design Guide - Glossary 网络 API（Networked APIs） 通过计算机网络中运行的应用程序接口。它们使用包括 HTTP 在内的网络协议进行通信，并且生产和消费 API 的往往是不同的组织。 Google API Google 服务的网络 API。大部分在 googleapis.com 域名上。...

翻译自 API Design Guide - File Structure gRPC API 应该（should） 使用 proto3 在 .proto 文件中定义。 文件中 必须（must） 将高层级和更重要的定义放在其他项目之前。原型文件 应该（should） 参照下面的顺序： 版权和许可协议（如果需要） 按照 syntax, packag...

翻译自 API Design Guide - Directory Structure 通常使用 .proto 文件定义 API，使用 .yaml 文件做为配置。 每个 API 服务 必须（must） 有一个 API 目录来存放定义文件和构建脚本。 API 目录 应该（should） 遵循如下的标准结构： API 目录 配置文件 {service}.yam...

翻译自 API Design Guide - Compatibility 本章提供了有关版本控制部分中给出的破坏和保持兼容性修改的详细说明。 并不总是绝对清楚什么是不兼容的修改，这篇指南 应该（should） 被当成参考性的，而不是覆盖到所有情况。 下面列出的这些规则只涉及客户端兼容性，默...

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

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

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

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

翻译自 API Design Guide - Naming Conventions 为了在长期和大量使用的 API 中提供统一的开发体验，API 中的所有名字 应该（should） : 简单 直观 一致 此文章讨论了接口、资源、集合、方法和消息的名字。 因为很多开发者的母语并不是英语，这些命名约定通过鼓励使...

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

| 名称 | 类型 | 描述 || - | - | - || name | string | name 字段应该包含相对资源名称 || parent | string | 对于资源定义和 List/Create 请求，parent 字段应该包含父资源的相对资源名称 || create_time | Timestamp | 资源创建的时间戳 || update_time | Timesta...

自定义方法指五个标准方法之外的 API 方法。应该（should） 只有当标准方法不能完成需要的功能时才使用自定义方法。一般情况下，API 设计者 应该（should） 在可行的情况下选择标准方法。标准方法有更简洁和明确定义的语义并且被大多数开发者熟知，所以它们更易于使...

此章节定义标准方法 List、Get、Create、Update 和 Delete。标准方法存在的意义是广泛的 API 中许多 API 方法具有非常相似的语义，通过将这些类似的 API 融合到标准方法中，我们可以显著降低复杂性并提高一致性。以 Google APIs 为例，超过 70% 是标准方法，这让它们...

在面向资源的 API 中，资源是命名实体，资源名称是其标识符。每个资源 必须（ MUST ） 有唯一的资源名称。资源名称由资源自己的 ID，任一父资源的 ID 及其 API 服务名称组成。下面我们将看一看资源 ID 和资源名是如何构成的。

这篇设计指南的目的是帮助开发者设计出简单、一致、易于使用的网络 API，同时它也帮助我们统一了 RPC API（基于 socket）与 REST API（基于 HTTP）的设计。

这是一篇网络 API 的通用设计指南，它从2014年开始被 Google 使用，并且指导我们设计了 Cloud API 和 其它Google API。我们将此指南分享出来希望能让人们更便捷地合作。

下面的文章翻译自 Google API 设计指南，翻译时的版本是2017-02-21 介绍 面向资源的设计 资源名称 标准方法 自定义方法 标准字段 错误 命名约定 设计模式 文档 使用 proto3 版本控制 兼容性 目录结构 文件结构 词汇表

IDEA装上go插件 或 gogland，功能强大，这里有一些使用技巧 web程序的话一般一些框架会对代码结构有要求，参考框架文档即可

邮件模版使用go template编写，两对大括号中的.ExternalURL即表示变量的ExternalURL字段，Data结构如下，源码在这里。请自行google go template的使用方法。