说三道四技术文摘-感悟人生的经典句子
说三道四 > 文档快照

Web API核查表:设计、测试、发布API时需思考的43件事

HTML文档下载 WORD文档下载 PDF文档下载
API设计并非易事,从设计到测试以至最终的发布需要经历一个漫长的过程,本文将主要探讨Web API从设计到最终发布,开发者可能忽略或者应该注意的事情,希望对你有所帮助。

当设计、测试或发布一个新的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、OPTIONS以及TRACE都属于idempotent操作;也就是说,“theside-effects of N > 0 identical requests is the same as for a singlerequest.” (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语义意味着要与用户案例相匹配。更好地介绍,你可以阅读DarrelMiller写的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”,如果它没有接受“100Continue”响应,在3秒的超时后会继续发送请求。如果API不支持“100 Continue”,或许会产生另一个性能缺陷,导致客户端禁用。

其它

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

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

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

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

上面提供的这份列表有趣吗?对你是否有帮助呢?欢迎与我们一起讨论。

来自:Mathieu Fenniak

OpenStack H版发布 盘点2013:21个最火的云初创公司 从摩尔定律到原子计算,2013诺贝尔物理学奖背后的计算机技术 黄峻:从自制纸板键盘的孩子到Adobe技术经理的故事 Web开发正被颠覆 开发者需认清五大新现实 最发人深省的亚马逊面试题,你会如何作答? 所见即所得:8款实用HTML5开发框架 Groovy最受欢迎 Java系开发者更偏爱其他JVM类语言?(图) [开源专访]iNews创始人赵戈戈:36小时开发的PHP版HackerNews 使用Spring框架的12个开源项目 甲骨文仍旧“憎恨”开源软件 开发者应该避免使用的6个Java功能 不可小觑的Web开发编码规范 软件工程师如同花园园丁,清理代码就好比拔草! 智能硬件元年 60+硬件展商引爆MDCC 2013 深藏功与名:Supercell CEO Ilkka Paananen访谈录 Google Ideas小工具捍卫言论自由 为什么谷歌要一直为摩托罗拉烧钱? 远见卓识,像CEO一样编写代码! [探讨]如何成为有代码洁癖的程序员? 消灭Bug!十款免费移动应用测试框架推荐 协同软件供应商Atlassian推出JIRA服务台 振奋人心!iOS和Android版BBM应用首日下载量冲破1000万次 十款开源的数据库管理工具 360联合多家IDC成立“安全防黑联盟” 国内百万网站受益 腾讯云如何玩转手游数据分析 成都站免费抢票 直接拿来用!10款实用Android UI工具 第14届英特尔投资全球峰会 新投16个项目逐一看 2013中国Linux内核开发者大会亮点汇总 UnitedStack:用社区的方式做IT 手游狂潮:小团队如何提高游戏数据化运营效率? 《程序员》的文章错字太多!!!!!!!!!!!! 关于指纹采集识别 高分求《j2EE服务器端高级编程》这本书的源码 MAKEWORD宏从哪里找到中文解释。 为何在重载CreateParams后指定Form的Height值小于某个值后就不会再小? 开发一个基于WEB的ASP仓库管理,用什么技术比较好。 怎样让弹出对话框居中显示 我用Server.Transfer来做两个页面之间传值,我怎么让页面成为新窗口打开呀,100分 高分请教XML高手 在InterDev中,我什么说我不能连接web server 请问 怎么响应一个按钮打开一个新页面,同时关闭旧页面 各位PM进来谈谈自己的经历和经验教训。 picturebox控件问题 jdbc的奇怪限制,不能reread row data UNIX支持中文否,请推荐UNIX好书 高分求助:怎样发布sapi.dll 我发现我变笨了!!或许我本来就很笨。但是问句实在的:IT会使人变笨吗? hal.dll文件丢失!winxp修复的问题!急! pb如何连接execl 用Windows2000Internet连接共享出现的问题,请各位大侠解决一下! 关于数据库字段大小问题 ★★如何给一个Dialog加背景图片?★★ MSDN Library 2003中文版3CD下载 我用access+adoquery+DBgrid,我在拖动改变dbgrid的列宽时,为何会报错? 关于软件汉化的问题。 请教:可以从硬盘上直接安装linux吗? C语言二级考什么题型 MYSQL是不是不能建视图啊?新手清多多指教 还是ASP与SQL联不上的问题,在线等待 请问:C:\Documents and Settings\user\Local Settings\Temporary Internet Files里的内容怎么删除 紧急求助!sqlserver服务启动不了 怎么知道当前这台UNIX的IP地址 getWidth怎么用呀??????????????? 我的是win2000 server ,怎么会老出现什么explorer.exe错误???? 申请免费空间 请大家谈makefile的写法 请大家帮忙 求助,Windows2003启动时提示 \windows\system32\config\system文件丢失或已损坏, 无法启动。 怎么样使程序调试结果在屏幕上停留时间长点 初学,请问Edit如何添加到Memo中? 如何制作安装程序? ******请问一下vs.net2002与vs.net2003是什么区别???***** 求助高手——怎样读取BIOS中的信息? 找个DELPHI的中文免费打包程?? 求书 正在填写“企业现有信息系统开发环境情况表”,上面有一栏“系统分析与设计工具”应填什么? 哪里有ASP.Net中在Combox下拉Tree的控件……?????急,急 菜鸟问题,仍然在线结帐,请进 谁能告诉我怎么配置环境和怎么运行c#的程序啊 关于WebBrowser的问题,请教 请教一个javascript的参数传递 模仿社戏写一篇作文800 我的笔买来都很好写的,为什么写了一段时间就不好写了?是水笔,黑色.黑笔刚买来都很好写,可是写了一段时间后就不好写了,断断续续的,能有什么办法让笔好写吗?应该买什么样的笔才从头到 牛皮纸写字舒服么?可以用普通黑笔写么? 请模仿社戏,写一段自己看电影或看演出时的作文 taking a big bite out continent-to-land 怎么翻译 写出与下列诗句反向立意的相应诗句例:劝君更尽一杯酒,西出阳关无故人。——莫愁前路无知己,天下谁人不识君。僵卧孤村不自哀,尚思为国戍轮台。——( ) 求送给朋友的祝福语 六神无主的六还可以组哪些成语? 青箬笠,绿蓑衣,斜风细雨不须归 单个字的意思 二分之一*三分之一+三分之一*四分之一+四分之一*五分之一+五分之一*六分之一 外媒:中国重视周边外交令日美警惕美被曝监听西班牙电话6000万宗引发越南民众聚集政府大楼前抗议挖沙公司破韩江原道前方哨所一士官遭枪击身亡 或翘臀又嘟嘴 壮汉翻拍“性感照”遭吐槽印媒:印度调整中国战略因不喜欢给中国日本进入“胖女时代”或因对瘦人审美疲人民日报海外版:监听门让世界彻底放弃移动设备进入美国儿童生活 使用人数两猫鼬欲擒毒蛇当美食 毒蛇凌厉反击赢得港媒:三中全会或开启中国“黄金时代”高雄市长参选人杨秋兴:陈菊欠黄俊英一彩站老板冒领600万大奖 被判返还合肥老人回忆当年在核武器研发警卫团工阜阳颍东区一居民种的2.5亩向日葵莫菲美举行两栖登陆演习从数字看成效 新疆生产建设兵团专项整广西集中宣判三起偷越国边境案 “蛇头重庆与世界文化嘉年华10月再启 英国亚运跳水男子双人10米台 张雁全/陈北京演出票房收入居全国首位盘古大观4.5亿工程款欠款纠纷缠十年
备案号:鲁ICP备13029499号-2 说三道四 www.s3d4.cn 说三道四技术文摘