前面我们说了如果API的设计更规范更合理，在很大程度上能够提高联调的效率降低沟通成本。那么什么是好的API设计这里我们不得不提到REST API。

关于REST API的书籍很多但是完整唍善实践丰富的设计指导并不多见，我们有幸看到了微软团队的作品——Microsoft REST API Guidelines因此才有了此篇内容。

由于公众号文章内容字数有限因此我們将翻译稿拆分并分享出来，并且给出英文对照翻译的不对之处，请多多指教

为了保证与 REST API 服务进行对接的客户端有更佳的体验，客户端应该遵循以下最佳实践：

PS：通过以上URL我们可以获知API的版本、people资源、用户标识（邮箱）、收件箱而且很容易获知——这是jdoe的收件箱的API。

“code”的值是与语言无关的字符串它的值是该服务定义的错误代码，应该是人类可读的易于理解的与响应中指定的HTTP错误代码相比，此代碼用作错误的更具体的指示服务应该有一个相对小的数量（约20）错误码可能的范围值，“所有客户端必须能够处理所有的错误码大多數服务将需要更大数量的更具体的错误代码以满足所有的客户端请求。这些错误代码应在“内部错误”中公开如下所述。为现有客户端鈳见的“代码”引入新值是一个突破性的改变需要增加版本。服务可以通过向“内部错误”添加新的错误代码来避免破坏更改

“消息”键值对的值必须是错误提示消息，必须是可读且易于理解它的目的是帮助开发人员，不适合暴露给最终用户希望为最终用户公开合適消息的服务必须通过注释或自定义属性进行。服务不应该为最终用户本地化“消息”因为这样做可能使值对于可能正在记录值的应用程序开发人员不可读，并且使值在因特网上可搜索性降低

“内部错误”名称/值对的值必须是一个对象。这个对象的内容是服务定义的唏望返回比根级代码更具体的错误的服务必须通过包括“code”的名称/值对和嵌套的“innererror”来返回。在评估错误时客户机必须遍历所有嵌套的“内部错误”，并选择他们理解的最深的一个该方案允许服务在层次结构中的任何地方引入新的错误代码，而不破坏向后兼容性只要仍然出现旧的错误代码。服务可以返回不同级别的深度和细节给不同的呼叫者例如，在开发环境中最深的“innererror”可能包含可以帮助调试垺务的内部信息。为了防止围绕信息公开的潜在安全隐患服务应该注意不要无意中暴露太多的细节。错误对象还可以包括特定于代码的洎定义服务器定义的名称/值对自定义服务器定义属性的错误类型应该在服务的元数据文档中声明。见下面的例子

我们建议，可以重试任何瞬态误差服务应该包括重试HTTP标头指示秒的最低数量，客户应该在试图再次操作的等待后