http://www.sunnybtoc.com/page/M0/S860/860373.html
当设计、测试或公布一个新的Web API时，你是在一个原有的错杂体系上构建新的体系。那么至少，你也要建树在HTTP上，而HTTP则是基于TCP/IP创建的、TCP/IP建树在一系列的管道上。当然，你也须要推敲Web办事器、应用法度框架或者是API框架。
API从设计到测试以至终极的公布须要经验一个漫长的过程，本文将首要商量Web API从设计到终极公布，开辟者可能忽视或者应当重视的器材。
HTTP篇
HTTP 1.1规范RFC2616是一个很是大的文档，下面我们节选了一些可能会对API产生影响的内容分享给大师：
1.Idempotent办法：GET、HEAD、PUT、DELETE、OPTI以及TRACE都属于idempotent操纵；也就是说，“the side-effects of N > 0 identical requests is the same as for a single request.” （RFC2616 §9.1.2）
2．验证：用户接见API须要进行辨认和验证，HTTP所供给的Authorization头文件就是出于此目标（RFC2616 §14.8）。RFC2617则指定了具体的验证规划，包含了最常见的HTTP根蒂根基验证。
3.201 Created：应用“201 Created”响应代码默示恳求成功，并且创建了一个新资料。201响应可以包含本地头文件中的新资料URI。（RFC2616 §10.2.2）
4.202 Accepted：应用“202 Accepted”响应代码默示该恳求是有效的，将会被处理惩罚，但还未完成。一般景象下是用在办事器后台队列可能呈现的处所。（RFC2616 §10.2.3）
5.4XX和5XX状况代码：4XX状况代码与5XX状况代码有一个很是首要的差别：4XX代码旨在注解客户端错误，而5XX则是注解办事端错误。（RFC2616 §6.1.1）
6.410 Gone：“410 Gone”响应代码是一个很少应用的响应式代码，其主如果通知客户端资料呈如今URL中，但实际上并没有。这个用在API里可以指明被删除、存档或过期的项目。（RFC2616 §10.4.11）
7.Expect:：100-continue：若是API客户端筹算发送一个大型的实体恳求，像POST、PUT或PATCH，它可以发送“Expect: 100-continue”到HTTP头文件里，在发送实体之前守候“100 continue”响应。这就容许API在返回错误响应信息之前，可以验证那些公道的恳求（例如401或者403）。应用它可以进步API的响应才能以及在某些情景下削减宽带。（RFC2616 §8.2.3）
8.对峙连接通顺：与API办事器对峙连接，对于多API恳求是个很是大的机能提拔。若是设备正确，每个Web办事器应当支撑keep-alive连接。
9.HTTP紧缩：HTTP紧缩可以同时用于响应体（Accept-Encoding: gzip）和恳求体（Content-Encoding: gzip），用来提拔HTTP API的收集机能。
10.HTTP缓存：在API响应时供给一个Cache-Control头文件。（RFC2616 §14.9）
11.缓存验证：若是你有缓存API，那么在响应时，你应当供给Last-Modified或Etag头文件，然后支撑IF-Modified-Since或者If-None-Match恳求头文件用于有前提的恳求。这将容许客户端搜检它们的缓存副本是否仍然有效，并且当没有恳求时，阻拦一个完全的资料。若是实现合适，那么前提恳求要比通俗恳求更有效。（RFC2616 §13.3）
12.前提批改：ETag头文件也可以用于前提批改资料。（RFC2616 §14.24）
13.绝对重定向：这是一个鲜为人知的HTTP/1.1请求，重定向（如。201、301、302、303、307响应代码）应当包含一个绝对URI本地响应头文件。很多客户端在本地支撑相对URI，然则若是你想让API兼容更多客户端，你应当在重定向时应用绝对URI。（RFC2616 §14.30）
14.链接响应头文件：在RESTful API中，经常须要供给转向其他资料的链接，甚至响应的内容类型无法供给一种天然体式格式链接（例如，PDF或图像）。RFC5988在响应头文件中指定了一个链接供给办法。
15.规范URL：对于多资料URL，RFC6596定义了同一的办法来规范网址链接。
16.块传输编码：若是响应内容太大，传输编码：分块（Chunked）是一种很好的流响应到客户端体式格式，它将会削减办事器和中心办事器的内存应用需求（尤其是对实现HTTP紧缩），并且供给更快的首字节响应。
17.块传输编码里的错误处理惩罚：在实现块传输编码之前，弄清如何处理惩罚产生在中心恳求时产生的错误是很是首要的。一旦对响应进行流处理惩罚，就无法改变HTTP的状况代码。
18. X-HTTP-Method-Override：有些HTTP客户端不支撑任何GET和POST，但你可以经由过程POST开通其他HTTP办法，应用商定成俗的标准X-HTTP-Method-Overrider头文件去定义“真正”的HTTP办法。
19.URL长度：若是API支撑错杂或随便率性的过滤项作为GET参数，那么记住，无论是客户端还是办事器端都可能会因为跨越2000字节的URL长度带来兼容性题目。
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测试是最简单的工作。它最好是主动化的，毕竟成果，须要好好哄骗它。
扫一扫
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
