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

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

Nike推创业孵化器:每个参与团队获2万美金 傲游发布云浏览器 支持跨终端数据同步 12个git实战建议和技巧 用友UAP产品线总设计师史周军访谈录 IE10新功能解析 支持Media Query(图) 单页Web应用或引领下一代Web新趋势? [CTO俱乐部第89期]新时代的前端开发 [多图]160台Mac mini打造的数据中心机架 是谁动了我的CPU! 欧朋CEO:GPU加速是手机浏览器的新趋势 TOP30专访:Splashtop研发中心总经理Alex Xu 2012Q3国内App开发者半数以上入不敷出 细微之处见真章 为什么要在try-catch-finally里加大括号 独立开发者:面对攻击就要“脸皮厚+更自豪” IBM纳米光子芯片对付大数据 单个通道25Gbps AWS数据仓库服务Redshift是最好的选择吗? 又赚了一笔:微软向两公司收取Android专利费 深度解析:Android4.2系统“应用验证服务” 欧洲移动游戏大会:五大行业趋势 大揭秘:Windows Phone 8 键盘输入的8个设计精髓 朝鲜:探寻最神秘的移动互联网王国 如何让IE 10玩转响应式网站 Windows Server 2012:令CIO激动的三个新特性 高德和新浪微博战略合作 打通账号互调数据 乐观锁和悲观锁 你更钟情于哪一个? Apple索30%分成 iOS版微软SkyDrive更新搁浅 [简讯] Linux 3.7发布 开源图形卡驱动程序 高效敏捷的十大经验法则 佛瑞斯特资讯公司预测2013年云计算的十个变化 百会中小企业CRM年会成功举办 发布CRM选型指南 诺基亚创新体验中心NEIC训练团正式开班 菜鸟提问:Form 与 Frame 有何区别? 以下是Delphi帮助的说明,谁能帮忙解释一下? 流星花园 我在image的click()方法里定义的变量,为什么在image_dblclick()里不能用?? 请教一下:金山词霸的屏幕取单词,是如何用程序实现的? 用VC怎么实现生成一个虚拟目录? 那位朋友有2000命令行模式下命令操作的帮助手册? IIS虚拟主机的问题,请大家给解决呀! 一个有关ListCtrl中拖动Column的问题。 请问那位大虾有用vc开发openssl的经验和原码? 兄弟我想学习数据库 但学什么好呐 给点意见 急求:将savedialog中多选的文件一次全都添进listview 谁有DirectX开发(SDK),给我一份,或留个连接地址 谁有DirectX开发(SDK),给我一份,或留个连接地址 怎样动态生成函数??? 你好!请问怎样给分? 高分debug!!!!!!! 再加50分请各位高手帮忙:http://www.csdn.net/expert/topic/598/598527.xml?temp=.1428339 请问各位,这种问题如何解决? from now , I'll come here usuauly 为什么邮件的接受时间会超前?高手请进来看看。 请大家推荐几本vc与汇编混和编程的好书 from now ,I 'll often come here. 请问: 中文版的 。NET 如何英文化????????????????? 高分debug!!!!!!! 怎样用vc编出来的程序能够隐藏起来,就象任务管理器那样 如何得到Query1->SQL->Add(select sum(xxx) from Table);的返回值? 谁能告诉我,这样得到的IPaddress 仅是本地dns解析的, 关于getdlgitem的问题? 如何得到登陆到服务器上的所有机器IP地址?????? 怎么样用C#在WEB页上画图形? 谁能告诉我,这样得到的IPaddress 是否仅是本地dns解析的? 请大家推荐几本vc与汇编混和编程的好书,请注明是哪个出版社出版 老问题:一个关于DLL输出函数的问题? 关于Win2K启动时程序自动加载的问题 Win2K里面输入法顺序调整的问题 同时有16个客户端从服务器端用FTP下载文件,但失败率很高,请问是什么问题 问大家一个C语言的教科书问题,谢谢了! 请高手明天,有关于JBUILDER6在XP下安装的问题 SOS ADO数据库中的varBinary字段的存取 TStream 怎么样改变标题颜色(不准用控件) 难道adaptive server anywhere6.0不支持中文吗? 我的窗口怎么处理不了方向键消息? 这是不是CArray的BUG?????????????? 关于如何修改历史记录文件夹属性的问题,,特急!!!!!!!!! 系统存储器和扩展存储器都在内存条上,是不是? 数据流传输的TNMStrm和TNMStrmServ组件和TNMUDP控件有什么不同啊? 在oracle如何这么做? 这给id中的可用分有很多!可惜等级不够,散分。不过也有一点小问题。解决了在给分。有GIS方面的资料吗?控件也行,你的大作也可以 有关SoftIce的用法,请各位帮忙! 请来拿分 各位怎么下载不下来LOTUS API 2.1 for window的?? 分母一定,分子和分数值成正比例. 把4改写成以千分之一为单位的数是( ),减少100个这样的计数单位后是( ),最低位是( ). 有错的吗,第二大题判断题, 求教第五题判断题 0.9改写成千分之一为单位是()这是他与原数相比是()他的计数单位变() 怎样向牛顿学习 分子一定,分母与分数值.能成正比例吗?并说说原因. 判断:一质点在某段时间内做曲线运动,则在这段时间内加速度一定不断改变. 牛顿学的是什么物理学? 芥菜和盖菜的区别 牛顿每千克是不是加速度的国际单位 数学怎样学才能达到牛顿的水平?牛顿是十七世纪的人,我们二十一世纪的人想超越他是一件难事吗?忽然觉得高中数学太肤浅了 芥菜和芥兰菜有什么区别? 一质点在某时间段内做曲线运动,在这段时间内为什么速度一定在不断的改变,而加速度可以不变 应该怎么学物理中的牛顿定律? 需要什么原料,具体步骤是什么, "牛顿"这个单位是计量什么的? 牛顿定律是哪个年级学的 牛一 牛二 牛三 定律 梅菜和雪里红有什么区别呀? “一质点做曲线运动,质点加速度方向时刻在变化.”这句话是否正确?为什么? 什么是矩阵力学? 小白菜和大头菜有什么区别? 一质点在某段时间内做曲线运动,则这段时间内速度和加速度如何变化.ps:顺便解释下原因, 1)水平地面放有两物体,已知A,B两物体与地面间的最大静摩擦力分别为8N和4N.若用一水平力F=6N,作用于A,则A对B的作用力为_____N,当水平力作用于B时,A对B的作用力大小为_____N.2)如图 如果x=九分之y,x和y成不成正比例,为什么 分数的分子一定,分母与分数值成不成正比例,为什么 已知万有引力常量G 地球半径R 地球的同步卫星距离地面高度h 地球转周期T 地球表面重力加速度g求地球同步卫星速度大小 和 地球的质量 物理摩擦力怎么求 怎样做`黄焖猪肉`?``` 判断题第2题是对的吗? 地球环境下真空内物体的质量或重力可否被忽略?如果知识面够广,可以同时阐述下地球环境形成重力的所有因素 需要什么原料,具体步骤是什么, 压力和支持力是平衡力吗?哪么重力和支持力呢? 谁有牛顿的英语介绍? 0.09的计数单位是 判断题第二题 牛顿的英文简介(越短越好)谢了! 0.09的计数单位是多少 第二题判断题 牛顿的英文介绍(六年级水平) 曲线运动是变速运动,因为做曲线运动的物体速度方向在时刻改变, 第二题,判断题 谁知道牛顿的事迹,in english 曲线运动是变速运动,加速度一定变化吗 如何改变重力加速度是否可以通过电流或磁场来改变 哈密顿变换,傅立叶变换,矩阵力学是什么 牛顿单位换算,我没学过,希望能详细点. 重力加速度的变化在地球上的同一个地方,离地面高度越大重力加速度g越小 对吗?请解释下为什么 谢谢~ 牛顿简介英文版1分钟 机械振动如何测量 平抛运动加速度方向时刻改变是匀变速曲线运动我们把加速度(或合外力)恒定的运动称为“匀变速运动”,把加速度(大小或方向或两者同时)变化的运动称为“变加速运动”.我混乱了 重力加速度什么时候有可能变成0为什么? 分子一定 分数值和分母 能否成正比例要用这种格式 例如:圆的周长和直径周长和直径是相关联的量 周长随着直径变化而变化 周长÷直径=π(一定)所以周长和直径成正比例 质量牛顿 单位换算 第二大题,判断题 分子一定,分数值与分母成正比例.( ) (是对的还是错的) 做匀变速曲线运动的物体 随着时间的延续 变小 为什么 可以画一个图吗 第二大题判断题全部 分子一定,分母和分数值,成正比例吗 求伽利略 哥白尼 开普勒 托勒密的天文学观点的不同处和相同处 还有最好能附上他们的观点模型图 和一些如果图片或资料来源于网站的话求地址 如果找到资料了直接给地址也行 第二大题,判断题全部求帮忙
备案号:鲁ICP备13029499号-2 说三道四 www.s3d4.cn 说三道四技术文摘