API设计篇

　　20.无状态：没有人希望API能够存储状态，即使是在你的应用程序服务器端。保持应用程序服务器状态自由，可以做到很轻易和很轻松地扩展。

　　21.内容协商：让你的资源支持多种表现方式，你可以使用内容协商(content negotiation，例如Accept头文件)，或者使用不同的URL(例如……?format=json)，或者可以让你的内容协商重定向到具体的格式。

　　22.URI模板： URI模板是一个定义良好的机制，用来提供URI组合能力到客户端，或者定义URL访问终端用户模式。

　　23.Design for Intent：不要仅通过API来暴露内部业务对象，设计API语义意味着要与用户案例相匹配。更好地介绍，你可以阅读Darrel Miller写的 API Craft。

　　24.版本：理论上讲，一个设计良好的API是无需创建兼容的。而对于实用主义者，它们会把版本放入到API的URL中(例如：a/v1/path)，所以，除非是处在一个安全的网络状态下，否则API可能不会按照预期那样工作。

　　25.授权：记住，当设计API时，并不是所有的用户都可以访问里面的任何对象。

　　26.批量操作：发送较少的请求来获取或修改更多的数据，最好的方法就是在你的API里使用批量操作。

　　27.标记页数：API中使用分页服务主要有两大目的：一个是减少不必要的数据传送到客户端;一个是减少应用服务器端不必要的操作。

　　28.统一的字符编码：在设计和测试API时，Web服务需要支持更多的英文字符。如果你在URL中把Unicode字节作为自然键使用，它将会非常有趣(例如：/users/jimbob/ becomes /users/??/)。

　　29.错误日志：在设计API时，创建错误日志也是非常重要的。实践时最好创建两种日志记录，一个是服务器端，一个是客户端。

　　内容篇

　　30.内容类型：关于内容类型(Content Type)可以写整本书，就个人而言，我比较喜欢重用他人开发的内容类型，像 Atom、 Collection+JSON、 JSON HAL或者XHTML。定义一套属于自己的内容类型会比你期望的更好。

　　31.HATEOAS：超媒体作为应用程序状态引擎是一个REST约束，简单点说就是你的内容应该通知客户端下面要做的事情，可以通过链接或表单来通知。

　　32.日期/时间：当你在API里提供日期/时间值时，应该使用一种格式，包括时区信息。 RFC3339是ISO8601的一个子集，是最简单的日期时间格式。

　　安全篇

　　33.SSL：无论你的API是否支持HTTP或HTTPS，你都应该考虑HTTPS这种访问方式，它的增长趋势日益明显。

　　34.跨站请求伪造(CSRF)：如果使用API的交互式用户与普通用户都使用相同的验证，那么你的API很有可能会遭受CSRF攻击。

　　35.Throttling：如果一个API用户的请求数超过了规定，那么你应该提供一个带Retry-After header的503响应。

　　36.婉转的拒绝服务：Throttling可以阻止你用最简单的方式进行攻击，但这里还有其他更机智的攻击方式。例如 Slowloris、 Billion laughs、 ReDoS，它们都不会占用太多资源，但是它们可以让你的API在瞬间耗尽所有资源。

　　客户端

　　无论你是否给用户提供测试代码或者是SDK开发包，都应该给他们提供一个客户端，并且遵循下面这几个步骤：

　　37.保持连接畅通：一些HTTP客户端需要做一些额外的工作来保持连接持久，持久的连接对感知API性能有着非常重要的影响。

　　38.授权之前的401：HTTP的另一个怪癖是，它们会在解决一个授权问题之前发出“401 Unauthorized”响应。这样就会延长API的请求时间。

　　39.Expect: 100-continue：至少有一个API客户端默认使用“Expect: 100-continue”，如果它没有接受“100 Continue”响应，在3秒的超时后会继续发送请求。如果API不支持“100 Continue”，或许会产生另一个性能缺陷，导致客户端禁用。

　　其它

　　40.文档：编写API文档是令人厌烦的，但是手写的API文档通常是最好的。编写时一定要包含这些内容：一些可运行的代码或者curl命令行，方便查阅。你也可以参考一些文档工具，例如： apiary.io、 Mashery I/O Docs、 Swagger。

　　41.设计与客户：不要在真空中设计API，要与客户打交道或者一起来设计API，参考用户用例。

　　42.反馈：在设计API时，应提供一个通道供用户进行反馈，

　　43.自动化测试：API测试是最简单的事情。它最好是自动化的，毕竟，需要好好利用它。

　　来源连接：http://www.csdn.net/article/2013-04-22/2814983-43-Things-To-Think-About-When-Designing-Testing-and-Releasing-your-API