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

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

【图文】走近华为企业业务与支撑万人技术团队的云数据中心 《习惯联盟》陈晓冬:与京东云合作让我们没有后顾之忧 流计算与批处理同现:畅享大数据时代的开源实践 挑战和机遇并存:大数据时代机器学习与可视化 【企业开源系列】收发一条Twitter推文的背后 在IE11中更快地获得您需要的内容 暴露程序员身份的8个行为 英特尔创新应用大赛大评审!创新也有中国风 苹果面临一问题:正源源不断地失去优秀工程师 初学编程者必知的五个网站 大数据基准测试专题论坛:基准测试是一把尚未完成的尺子 大数据应用(下):应用驱动技术,DaaS创造价值 大数据研究与发展专题论坛:大数据在各领域中的应用及发展策略 雅虎新目标:欲收购照片分享网站Imgur 移动开发工具访谈《近匠》第01期:七牛云存储—BaaS进化论 ShareSDK:A轮融资到位!将推社会化评论SDK 70美元,你也能用Raspberry Pi做个专属iBeacon基站 7个鲜为人知却超实用的PHP函数 从管理远程式团队和分布式团队中所获得的宝贵经验 Netflix开源数据流管理器Suro Google新创意:天花板加麦克风 人脑植芯片 苹果获弯曲屏新专利 可给手机弄个大波浪卷 真正的跨平台硬件测试:3DMark已打通PC、iOS、Android 将Chrome浏览器变成终端工具 【开源推荐】AllJoyn:打造全球物联网的通用开源框架 21张图带你走进Google数据中心 Snapchat C轮融资5000万美元 投资方是Coatue Management 又一个被谷歌寄生的平台,Chrome应用启动器现来到OS X上 雷军遇上刘德华:创业、艺术、移动互联网 为了抗衡Android,传微软开始考虑WP和WinRT免费 维护代码库的五个精华实践 非典嚣张的日子里的北京(希望惊起大家对SARS的关注)!!! 问一个简单的概念性问题,分却很多.......还可加哦 一个数据映射错误 关于进程通讯的问题 问一个简单的概念性问题,分却很多.......还可加哦 哪里可以找到关于OA方面的资料?越多越好,100分送上 高手请进,怎么监测到一个文件将被覆盖 请问如何屏蔽F1查看帮助的功能? 高手请进,怎么监测到一个文件将被覆盖 能提供解码器么? 在tdi中,怎样获取封包ip头? 神啊!救救我吧!!!!(在线等待) 我看SARS危机 求助 我该怎么办??? 管理登陆问题解决?? 一个简单的问题,如何对字符串进行减操作? 谁用过struts,进来交流一下! 请大侠看看俺的小程序,哪里错了(关于不规则图形填充) delphi查询问题(急需) 急求:从硬盘安装windowsxp时电脑出显不能安装,找不到eula!如何解决? 系统分析员VS博士 C#连接Oracle? 关于<BASE> 那里有WebDB下载啊. 在ListCtrl里加类似Combo Box的东西,能实现吗? windows2000下vb的一个小问题~~ 如何把当前路径加入查找路径中?立即给分! 对选用不同的纸张大小,在预览中能看出效果吗? 请问怎么在PB6.0中实现Foxpro(*.dbf)的数据导入,到ASA库中 j2me里怎么才能实现图象的滤镜效果?waiting... CDbSet m_dbSet(NULL)在哪一步才能得到一个CDatabase对象的错针? 新手提问:“镜象”是什么意思 求教,如何配置使性能达到最佳,详情见文 怎样在广域网中提高传屏响应速度?帮帮忙!急啊. 在文件钩子当中如何判断是打开文件操作,还是创建文件操作 怎样在applet程序中显示一幅jpeg图片?该图片存在于c:\image\下。 去年12月是谁发的帖子“做项目经理难么” 关于图层拖拽的问题 我有一块硬盘,迈托4.3G,开格式化分时说错误设备或0磁道损坏,后来fdisk分区,启动无效 这是个什么错误啊~ 第一次做控件不明白 给点指点啊 急求:从硬盘安装windowsxp时电脑出显不能安装,找不到eula!如何解决? 不用的控件怎样从工程中删除? 怎样将一个表中的全部数据追加到别一个表的后面????在线 我做软件这些年 求scjd的模拟题 为什么我连续给一个socket send三次,socket一次就接收完了? 关于HTML代码不区分大小写? 大家看一下这个CListCtrl是啥回事?? Turbo c++3.0怎么使用? 《水园MSN俱乐部宗旨》 在△ABC中,a,b分别是角A和角B所对的边,a=根号3,b=1,B为30°,那么角A的值为 截距在数学上,指函数与坐标轴所有交点的(横或纵)坐标之差,可取任何数?这句话是神马意思? 原电池 【化学高手进】如图所示的装置中,在产生电流时,以下说法不正确的是A.Fe是负极,C是正极B.负极反应式为:Fe-3e-=Fe3+C.内电路中阴离子移向FeCl2溶液D.电流由石墨电极流向Fe电 在三角形ABC中 a=1 b=根号3 A=30° 求B? 臭氧、黄铜、水三者一起会发生什么反应?即臭氧通入水中,含臭氧的水流过黄铜水管,结果如何?黄铜在水中遇到某些氧化剂,氧化是肯定的.听说铜、锌、水三者之间会产生一种电介质,并加速腐 为什么浓硫酸能作为酯水解的催化剂阿,它不是会吸水吗,反应不就像逆反应方向生成酯了吗?那都可以用碱干吗还用稀硫酸阿?在说了 我们在写酯化反应时 用的箭头是双箭头,条件是浓硫酸,你 水下污染物的毒性实验怎么做? 能否说质子酸都是Lewis酸? 罗马斗兽场是用什么石头建成的?雕塑呢? 实验中 尾气的定义是什么? CH5+为什么是质子酸而不是Lewis酸 07年化学竞赛初赛有一道题大致意思就是这个但我读到的书说 所有布朗斯特酸都是Lewis酸 使我产生了迷惑CH5+为什么是质子酸而不是Lewis酸 离子方程式为Zn+2H+ =Zn2+ +H2.可以设计成电解池和原电池 那么电离子方程式为Zn+2H+ =Zn2+ +H2.可以设计成电解池和原电池 那么电极可不可能是同种材料?比如呢., 冶练厂排出的尾气有没有毒 HF是质子酸,但是F有孤对电子,可以做lewis碱吗? 一直某池(原电池或电解池)的总反应离子方程式是Fe+2H*=Fe*+H2 该池是什么池如果是原电池,为是那么不能是电解池 如何使信号发生器输出一个频率1000赫兹电压峰值为5伏的正弦电压信号的操作步 请问这句深奥的话是什么意思?咸菜虽不是主菜,却容易下饭!但咸菜总归是咸菜,别一时糊涂当成了主菜!暗示着什么含义? 右图装置中发生反应的离子方程式为zn+2h 毕竟西湖六月中 什么石头可以雕刻石像 居民楼燃气爆炸谁承担后果 设计一个信号发生器产生1000赫兹的正弦波信号,经过功率放大使功率在一到十瓦之间,误差在百分之20以内谢谢需要三个电路,稳压电路:把交流点经整流滤过变成稳压电路.信号发生电路:产生 这些深奥的话究竟是什么意思呢?人生若都是喜剧,那就不叫人生了.我们不需要眼泪,如果欣赏艺术也要欣赏悲剧的话,那就欣赏自己的人生算了.成熟也是一种人生. 小苏打能不能除去自来水中的氯离子?我家养的乌龟一直用自来水,最近好象生病了,可能是自来水的缘故,我想用大苏打除去水中的氯离子可是没买到,只有小苏打不知道小苏打有什么用,是不是 超市中转基因的食物有哪些 毕竟西湖六月中,下句是什么 用小苏打去除自来水的氯比列应是多少?百度上不是都说小苏打也能除氯吗? 淘宝网特卖频道是真的吗 毕竟西湖六月中的意思意思!快,最好是简洁的,不要其他,只要意思 《快乐酷宝》里哪台天文望远镜更好用? ZnCl2 和NH4Cl的混合溶液中还有杂质CuCl2,会加速对电池的腐,想去Cu,为什么最好用 Zn其实这是道选择题 A NAOH B Zn CFe D NaCO3 我们平时吃的药怎么杀灭细菌和病毒的 “神经递质与受体结合后,突触后膜产生兴奋.”这句话错哪了? 解释:机遇只给有准备的人(不用太深奥) 辐射可以杀细菌或者病毒吗?电脑的辐射可以么? 神经递质通过受体进入突触后膜,是什么跨膜运输方式 毕竟西湖六月中,下一句是什么 混沌数学该怎么研究?你想买一双鞋,1000元.你管你妈借了500元,管你爸借了500元,然后买双鞋花了970元,剩下30元,换你妈10元,换你爸10元,还剩下10元.于是你欠你妈490元,欠你爸490元,等于一共欠他俩4 2000名儿童参加爬山,海底世界和当秋千三项目,规定每人要参加两项目.至少有多少人参加的活动项目相同 资本主义是什么?不要太深奥 数学中的非线性映射具体是什么意思?现在在混沌系统理论中经常可以看到这个名词. 非零和对策的特点有哪些? 什么叫测试病毒 古诗三百首 毕竟西湖六月中, 请问有没有不带脏字的骂人的话?深奥的,傻子听不懂的那种.有个猪婆一见就打我骂我!还说些骂人的话. 在氯化铜溶液中..CU离子与氯离子的关系是?..A.=1:2 B.1:2 D=1:1 两种常见铵盐受热分解后无残留物质写出有关方程是 一些关于什么的深奥的话!就是要那种的话像:叶子的离去,是因为风的追求,还是树的不挽留?就要类似这样的,用物喻人,要经典的,在要些教育人的话,不要太长的, 拿什么测验病毒 混沌数学是什么? 深奥点的话别人看不起我 谁给我想一句话要深奥的那种做我座右铭!努力奋斗!让曾经那些看不起我的人刮目相看 青刀豆是转基因吗 求金属和铵盐反应方程 深奥的话帮忙写些关于儿童的青年也可以- - 凉拌青豆角怎么做我看到加了蒜头等 很深奥的话,不俗的那种很有意思的句子 水处理后的浓盐水可以用磷酸三钠处理防止水垢生成么水师由水处理车间处理后的浓盐水,我们用来冲渣,但存在结垢问题,是否可以用磷酸三钠处理? 需要什么原料,具体步骤是什么, 像西湖这样的名胜我们中国还有哪些 橡胶模具O型圈板模哪里开得好,错模量,型腔尺寸一致性,型腔表面粗糙度这些质量都非常好,各位帮推荐一个 收入分配改革或从初次分配“提低”突破女子3个月内分饰24角骗40名男子 男子与15岁少女发生性关系 因女子胸温州女教师深夜家门口被袭胸(图)美国国家安全局:奥巴马对默克尔被监听温州办公用房改革搁浅 官方表示执行起感召侨商回归 聚焦浙江发展浙商大会吹响转型集结号 签约项目总投知名浙商代表倡议天下浙商整治农村污水浙商后代谈“幸福观”:分享是幸福 活吴建民寄望海外浙商:记住中国的家 也宗庆后支招新浙商创业重在创新 不要走杭州两年前规划建9个公园地下车库 现中国核潜艇部队官兵多在出海前写好遗书俄“连坐”严惩恐怖分子韩国要美回复是否窃听韩总统报告显示中国顶尖富豪财富激增 168告别“南斯拉夫”埃前少校疑刺杀内政部长印东北部连环爆炸5人亡安倍再提推进探讨行使集体自卫权广日白云车展 五一有得Fun专家:和平共处五项原则体现国际关系民和平共处五项原则60年历久弥坚 契合罗冲围客运站将重新选址专家:IE用户可用第三方浏览器马九器:不除赛场暴力哪来公平竞争政府购买服务解决“托管”难3名涉枪在逃嫌犯落网你来,或者不来,我就在这里春山秋韵(中国画)《广州日报·河源社区》昨日正式创刊出亲,当心强对流来袭启事·情感天地八亿元 九千人次 非法集资又造孽8天3赛,但体能不是问题立白携丹麦诺维信推动洗涤用品创新公众责任险是医患关系“防火墙”凤岗三鸟市场昨天拆了公交到哪了 手机将可查谁能看见最后的“光明”韩国总理辞职背后 “韩国政府有担当”
备案号:鲁ICP备13029499号-2 说三道四 www.s3d4.cn 说三道四技术文摘