标签：
近年来，微处事架组成长迅速，SparkPost 就是早期落地微处事架构公司之一，他们发明落地微处事过程中，不光需要考虑处事发明、处事注册、处事挪用跟踪链等等架构问题，也需要重视微处事 API 的变换打点。微处事的一大特性就是独立颁布，快速迭代，但前提是足够不变，他们在使用微处事构建API的过程中就遇到很多问题：客户（微处事使用方）经常反馈 API 升级变换后不成用，有时影响范畴不成控，导致该微处事上线延期，甚至线上故障，违背了微处事初衷。
API 参数变革或返回功效变革而导致客户端行为不一致，依赖客户端需要大量重构，团队不能专注在创新型事情。
API 易用性差， 使用方技术栈不统一，各行其是 API 抽象及封装，容易堕落。
缺少文档及使用引导，需要大量撑持事情。
凭空捏造，产出微处事往往不能满足需求，运行一段时间就会逐渐废弃。
SparkPost 颠末多年的探索与实践，总结了大量最佳实践，指导他们构建长期不变的微处事 API。现如今，它们的 API 被成千上万的客户使用，包孕Pinterest、Zillow 和 Intercomto，每月发送赶过150亿封电子邮件。
在这篇文章中，我将回顾几个选择和最佳实践。
RESTFUL 是最好的，但要实用，不需要学究式首先，也是最重要的一步，我们采纳的法式是决定使用 REST 作为 API。我们的理念是选择以下三个要素作为我们的 API 的根本:
1.HTTP : 这包孕响应代码和操纵符。操纵符包孕 POST、GET、PUT 和 DELETE，它们可以映射到根基 CRUD(创建、读取、更新、删除)操纵。
2.EESOURCES : 这些是 HTTP 操纵人员执行的实体。
3.JSON (JavaScript 东西暗示法) : 这是一种通用的数据交换格局。
这三个元素供给了实用 REST API 所需的一切，包孕简单性、可移植性、互操纵性和可改削性。在构建了 API 之后，用户可以轻松地对其进行集成，而不考虑他们的编程语言，包孕 C#、PHP 和 NODE.JS, JAVA，甚至是 SHELL 中的 CURL。他们可以不用担忧潜在的技术成长，包孕多种微处事。
当我们创建 SparkPost API 时，我们试着不要太过学究式地使用纯粹的 REST 模型，而是选择易于使用。下面是两个可能不遵循 RESTFUL 最佳实践的示例:
1.GET /api/v1/account?include=usage
2.POST/api/v1/sending-domains/example.domain.com/verify
第一个示例使用盘问字符串参数来过滤实体中返回的内容。在第二个示例中，我们在终端名称中使用“VERIFY”这个动词，这可能不切合 RESTFUL。我们会讨论每个新的用例，并尽力确保它的一致性和易于使用。
成长进化并打点变革我们有许多开发人员和团队在使用我们的 API 的微处事，并在连续的变换。当工程师确定它已经通过了我们的测试时，我们就会自动将变换部署到出产中。
我们很早就决定让我们的 API 在使用惯例和如何打点变换方面连结一致。我们成立了一个治理小组，此中包孕代表每个团队的工程师、产品打点组的成员和 CTO。这个构成立了并强制我们遵守的 API 约定，并且是完全文档化的。
文档化的约定让我们可以减少不一致，并且更容易界说每个新的端点。以下是我们成立的一些约定:
在单词定名时，URL 路径是带有连字符的小写字母，并且区分巨细写。
URL 盘问参数和 JSON 字段也是小写的下划线，并且是巨细写敏感的。
请求主体中的非预期盘问参数和 JSON 字段应该被忽略。
治理组还为如何进行变动以及允许哪些类型的变动设置了根基法则。有一些很好的 API 变动对用户是有益的，并且不会粉碎它们的集成，包孕:
一个新的 API 资源、端点或现有资源上的操纵。
一个新的可选参数或 JSON 字段。
在 JSON 响应主体中返回的新字段。
相反，一个粉碎性的变革包孕任何可能粉碎用户集成的对象，好比:
变动字段的数据类型。
一个新的必须参数或 JSON 字段。
删除现有端点或请求要领。
现有资源要领的本色性行为差异，例如将选项的默认值改为“TRUE”
做任何改削时不要制造粉碎即使它们是修复 BUG 或不一致的功效，，也应该制止产生改削。凡是在这种特殊的情况下运行比粉碎与客户真个集成危害更大。如果变革是多样的，我们会非常谨慎，寻找其他要领来实现我们的方针。有时可以通过简单地允许用户通过帐户设置或 API 参数变动其行为来实现。
然而,总会有一种情况引入变革对我们用户的利益胜过任何潜在的倒霉因素,将引入的变革。但是在这些情况下，我们遵循了这些最佳实践:
我们分析了 API 日志，以了解变动可能会影响几多用户。
我们给用户至少30到60天的提前警告。
我们发了一封邮件或发表了一篇博客文章，里面包罗了关于转变的详细信息以及我们为什么要做这些转变。
我们在 API 文档*给了升级指导。
“一个版本”法则