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

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

处理过程时的鼠标显示 -VB资料 窗口处理技巧大全 -VB资料 窗口事件的发生顺序-VB资料 VB创建不规则窗口 VB创建透明窗体 VB创建位图菜单 VB创建无 Icon 的窗口 打开 Win95 的创建快捷方式窗口-VB资料 打印机技巧 -VB资料 带有历史记录功能的菜单-VB资料 得知目前Mouse所指的Menu Item是哪一个-VB资料 调整 Combo 下拉部分的宽度 -VB资料 对象是使用 TAB 键还是鼠标激活的 -VB资料 防止用户编辑文本框控件中的内容-VB资料 改变 ListIndex而不发生 Click 事件 -VB资料 改变 TreeView 的背景 -VB资料 改变安装向导的背景色-VB资料 改变按钮的文本颜色-VB资料 功能强大的增强列表框 ――VB6控件LISTVIEW使用指南 关闭MDI窗体中所有的子窗体-VB资料 规范设计Windows应用软件菜单-VB资料 VB建立可滚动的视区 -VB资料 VB建立可下拉选择的属性 -VB资料 VB建立无模式窗口 -VB资料 将VB5中的ToolBar变成平面的 将程序从任务列表中隐藏 -VB资料 将我自已的命令加入窗体的控制菜单栏-VB资料 VB利用 UnloadMode 来控制窗体的卸载? VB利用Form_QueryUnload询问使用者是否关闭窗口 利用VB的图片框实现屏幕的滚动 利用VB动态改变Windows显示模式的两种方法 急急急急急!!!!!!!!!!,Band里的内容过长,如何让它自动的分页??? oicq的窗口title怎么为空了?如何得到句柄? session问题! 用dbgrideh控件,如何实现汇总结果的打印 有关ATL的最基础问题 怎样监控icmp包?用自编的程序 急急急急急!!!!!!!!!!,Band里的内容过长,如何让它自动的分页??? 使对话框最小化渐变到托盘区。 各位高手!!我用的是win2000工作组模式,为什么我能访问别人,而别人不能访问我呢??? 有关文件的读写问题。 大家讨论一下内存分配、释放的问题 关于在jsp中运用sqlserver的小问题!!! 怎么样可以将session的存活期限设置成“永远不死”?? 送分题,如何取得一个表的所有字段名? 那里可以下载Wrox系列书的英文版? 无法启动sqlserver的问题. DELPHI中dbgird的语句问题 关于控制动态产生Checkbox,并进行动态控问题 BCB中使用MSComm控件,无法定义动态数组变量,该怎么办?--急啊!在线等待 战神----巴蒂 两个问题! 用ADO访问DBASE数据库 百分求救:关于COM方法的reference参数不返回值的问题 请教各位高手 如何将程序中不同的查询结果写入报表? 怎样自编程序监控icmp包,应该截获什么消息,还是用别的方法? java本地化的问题(各位帮帮我!) 一个关于类型转换的菜鸟问题!! 招聘 Jpeg中FFd9可以有几个? ?????不同窗口中多个参数传递的问题,在线等待中........ 关于 EmbeddedWb 的Mshtml_tlb, SHDocVw_tlb 问题! 各位大虾 帮我翻译一下 急 悲... DBGrid为什么没有数据集记录失去焦点事件? 怎样手动和在程序中更改SEQUENCE的当前值? 怎么结贴子,什么叫FAQ? 关于“软件蓝领”的3个疑惑。 在函数中以引用方式调用结构的问题?给我能给的最高分100 怎样实现随机打印一个数据表的几个子段? 大家看看,这个功能如何实现? 怎样编一个程序读取服务器上的时间? VC工程不能正常打开? Jpeg中FFd9可以有几个? datawidgets简介!简单的问题---“送大伙一点小分” 新人到!!有问题想要问!!! 有谁知道sybase12.5中定义的所有保留字keywords? 为什么我的Tomcat突然找不到Serverlet了 关于报考程序员的问题 请问:一个应用程序发布时需要为每个发布的实例建立一个唯一标识用GUID好不好? 介绍些ActiveX/COM的好书吧! 1.用锤击钉,设木板对钉子的阻力跟钉子在木板中的深度成正比,每次击钉时锤子对钉子做的功相同,已知击第一次时,钉子进入板内1cm,求击第二次时,钉子能进入木板的深度.2.速度为v沿水平方向 怎么跑100米和200米啊?星期三就要比赛了. 地热供暖疑问《不热》我家是电厂统一供暖,5楼,83平 地热3组 把冷山墙.4楼6楼停暖 ,测量出水管温度37°现在室外温度-17°,我家室内温度15度左右,地热已经清洗.气也放了、过滤阀也清洗了.现在 c switch 问个 switch (i) 函数中case后面只能跟常量吗?可不可以这种写法case :i>1 && i=35 &&i 岩土的热物性是什么意思啊 致100米、200米、800米、4*200米运动员 关于c中switch的应用企业发放的奖金根据利润提成.利润I低于或等于100000元的,奖金可提10%;利润高于100000元但低于或等于200000元时,低于100000的按10%提成,高于100000的部分,可提成7.5%;200000 讨论非恒定加热功率以及出现断电的情况下怎么算岩土的热物性,探讨用非恒定的加热功率是否能缩短测试时间, 什么是实验室反应釜?它的作用是什么? 在一个2米高的圆形水池底部开个3厘米的孔装台微型水轮机来发电,能不能带动一台50至100W的发电机呀?我想用家里2米的水池来发电~~ 离子通道与钠钾泵的区别? 最近家里蚊子特别多怎么办哦!求大神帮助 溴化锂机组要多少溴化锂以 200W 大卡 为例 需要用多少溴化锂溶液 不锈钢反应釜的作用(放在烘箱里加热了) 海南的蚊子为什么那么毒?被叮一下就肿起一个大包,隔天都还会痒,讨厌死叻! 远大溴化锂机组报价、双良溴化锂机组报价、LG溴化锂机组报价、开利溴化锂机组报价、三菱溴化锂机组报价 position switch是什么意思 为什么澳大利亚的蚊子这么毒阿大神们帮帮忙 SWITCH的初步认识 code switch是什么意思 家里的蚊子.苍蝇从哪里来?如何才能彻底消灭它们?求大神帮助 如果你家中有乐器,观察一下它是怎样发出声音的,又是怎样改变音调和响度的?具体说一种乐器,具体点行吗?thanks! 吸收式制冷的工作原理是什么 第13频道至第68频道属于微波中的“分米波”,试着算出第68频道的波长范围就知道这个呼称的原因了. 自制乐器,要求能改变响度,音调,能发声.声音改变要比较明显今晚之前要知道 求热电致冷材料的工作原理!不过能不能再说清楚一点呢?n、p半导体我知道,可是原理我还是不清楚啊! 阅读短文,回答问题:为了满足人们对能源不断增长的需要,科学家们设想在空间建立太阳能电站来利用太阳能.这种空间太阳能电站建在地球同步轨道上,其工作过程如图所示.在太阳能收集 通常有几种乐器?每种乐器的发声体是什么?每种乐器怎样改变声调和响度 单层玻璃反应釜如何加热?有人知道吗? 光学波长频率的计算红光在水中的波长和绿光在真空中的波长相等,水对红光的折射率是4/3,则红光和绿光在水中的频率之比为?我要过程,和解释? 下列现象中属于做功使物体内能增加的是:A水蒸气将壶盖顶起 2用火炉给水加热 3钢条在水泥地上摩擦变热 4用太阳能热水器对水加热 单层玻璃反应釜的工作原理是什么啊? 微波属于?,但其波长较短,频率较高. 下列现象中,内能对外做功的是:A.冬天在户外时两手相搓一会儿就暖和B.刀在砂轮的高速摩擦下溅出火花C.在烈日之下柏油路面被晒熔化了D.火箭在“熊熊烈火”的喷射中冲天而起求详解一下D 单层玻璃反应釜的工作原理是什么啊? 书上说:“体系只做体积功而不做其他功时,恒容反应热等于体系热力学能的变化”.那我有个疑问,它说是只做"体积功",做体积功是要变体积的,但又说是"恒容反应热",但"恒容"又是不变体积的, switch 什么意思? 汽车无极变速器(CVT)它的原理是什么? Q(热量)、T(热力学温度)、V(系统体积)、W(功)、ρ(密度),其中属于状态函数的是 下列现象中,由于做功而使物体内能增加的有A,煮开水,水蒸气把壶盖顶起:B 打气筒打气时,筒壁会热起来C 用手来回弯折铁丝,弯折处会烫手D 用锯锯木头时,锯条会变热(简要说下理由,我觉得B 火电厂中什么气体可看作理想气体?什么气体可看作实际气体? 塑胶熔点与阻燃性的关系 下列现象中,利用做功改受内能的是A、晒太阳感到暖和 B、用蒸笼熘冷馒头C、感冒发烧,用冷毛巾敷额头D、插上电的电炉,炉丝烫了 卧式反应釜的加热系统如何做恩?说说啦 牧童这首诗中抓住什么进行描写 switch position是什么意思 应该是溶解度单位.还有这个Ncm3/g?不知道那个3时不是个上角标.n为什么要大写! 举例说明古今声调的关系(文字说明,从古声调至今声调,再从今声调至古声调) 神经细胞钾离子钠离子通道是什么 我400米59秒 800米2分20秒 请问我100米.200米正常应该跑多少?我400米59秒 800米2分20秒 请问我100米.200米正常应该跑多少?我14岁 175cm 60KG注 我短跑不是很厉害 家里地热的问题 供暖我家是复式的房子 家里都是地热 现在发现 一到供暖的时候 楼下的地热就自动过水 自动循环的流动 但是楼上的地热却是都是空气 把空气放出去 就能听到水在流动 钠钾离子通道是不是既有主动运输又有被动运输,那什么时候主动什么时候被动? 若不慎将油汤洒到衣服上,可以用什么办法出去,说明依据的原理-_-|||高一化学.. 离子浓度大小判断,D选项哪里出错呢?.A选项感觉也不对,A选项对吗?麻烦详细解释 蚊子闻到蚊香的气味,是晕?还是死? 汽车变速箱中的齿轮是一档齿轮大还是五档齿轮大? 什么是地热供暖 为什么蚊香熄灭后,蚊子又出现了?蚊香是驱赶蚊子还是杀灭蚊子? 鼓怎样改变音调 音调的单位是如何定义的
备案号:鲁ICP备13029499号-2 说三道四 www.s3d4.cn 说三道四技术文摘