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

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

《近匠》专访AbleCloud李海磊:IoT平台求变 腾讯、京东、微软等设计专家齐聚,探讨移动应用体验创新设计 TIOBE 2015年5月编程语言排行榜:微软系语言份额上升 《Hadoop核心技术》作者翟周伟 :我与Hadoop的不解之缘 云集百位核心专家 中国云计算大会演讲议题公布(表) 细品这杯香浓的咖啡——阿里中间件高级专家沈询的Java之旅 超图研究院院长李绍俊:创新2.0时代的平台软件研发体系 优麒麟(Ubuntu Kylin)15.04发布派对在天津成功举行 【CTO讲堂】以API为核心的移动应用云大发展时代 游戏设计的迭代误用:从半成品到概念修正 成功的社区在于拥抱变化——知乎创始人周源专访 优化UITableViewCell高度计算的那些事 国外iOS大牛:开发Apple Watch应用我犯过的错 云上Java System Profiling与Debugging——蚂蚁金服观察与实践 搜狗商业平台Java技术实践 Java在电信软件领域的技术实战 关于Java框架Vert.x的几点思考 Java在游戏服务器开发中的应用 Java框架研发思考 那些年,Java程序员用过的开发工具 Java内存模型的历史变迁 Java 8与Apache Ignite Java开发与技术挑战——关于技术的技术思考 专访唯品会架构师肖桦:做编码的架构师 越来越“简单”的Java 我的Java!越过山丘 专访沙梓社:做个“Think Different”的技术牛人 基于ES6,使用React、Webpack、Babel构建模块化JavaScript应用 财税街创始人石克清:创业须空杯心态+有效社交 自我知识管理:连贯性就是生产率 玩转Google I/O 2015:Android M、IoT、Glass 2.0、VR、ATAP 求助capboy等网络视频播放高手!!! 菜鸟问题:在VC中用ALTER TABLE指令需要什么头文件? 请高手帮忙,感觉难度很高 大家做GUI时有什么好用又免费的日期控件呢? 在javabean中用sql server2000的jdbc驱动连不起数据库! 添加图片到数据库中,奇怪现象! 如果我已经得到了一个DOM树, 我第一次运行HTML HELP时,new怎么会是无效的? 我的 程序在调用FORM.ACTION的用法不正确。能告诉我怎样用它 怎幺样实现一对主从表的数据库基本操作?用ADOQuery连接SQL2000. 有关统计打印的问题 一个关于用VB调用C++builder编写的DLL文件,DLL的API函数中存在函数指针。请各位高手给点意见! 大专生如何考研?(up有分) ★★ 为高兴而送分 ★★ 关于打印的问题,请各位帮忙 请问应该用何种信用卡 利用INTERNET远程连接问题 移动办公相关问题?如在两台机器里编写同一段Web程序。 怎样将oracle sql中的in语句改为exists语句? 求教win 2000双网卡上宽带的问题,请高手帮忙! win2000,给文件改日期的命令是什莫??? 为什么我的背景图片显示不出来? 请问如何在DAO的SELECT语句中使用COUNT等运算符? 请教:请问在程序中怎么在Check box 前边的小框上打上对号 老板让我一个月内学会vb,大家说可能吗? 我装了project 2000后,原来的office 2000只能用50次了,怎么回事? 请能提供DES和RSA算法的源程序呀,vb或VC的都行,最好是VB 请问如何让一个报表的内容同一个DBGrid一致,可以自由设置字段的是否显示? 我用vb新建了一个文件请问如何能双击就能打开我的程序,就跟word一样例:我新建一个kk.doc 只要双击kk.doc 就能打开word 使用Enumwindows的问题 我的jsp页面能够运行但是WEBLOGIC显示了<2002-9-2 上午10时41分13秒> <Error> <HTTP> <Connection failure 大家是怎么看下载来的MFC的程序原代码的? 在JAVASCRIPT中,我怎样用语句控制一组选钮中那一个被选中? 如何对 redhat-config-network 进行配制? 各位师兄:哪里可以下载讲Delphi6多层结构的教材?很急!!!! 小问题 看完了钱能的《C++程序设计教程》继续深入下去该找什么书来看看呢? 关闭窗口 除了onunload 是否还有其他事件? 为什么我的电脑每个目录下都有一个folder文件? 请教一下:delphi6中nmftp的用法 急!!!水晶报表问题 用代码把数据窗口指定到某一打印机打印? 如何配置jConnect连接Sybase数据库?需要安装jdk吗? 奇怪的出错:java.lang.NoClassDefFoundError: com/sun/java/util/collections/HashMap 我装了project 2000后,原来的office 2000只能用50次了,怎么回事? 各位有没考虑过买房一事,看看北京的房价再看看我的收入,怎么办??? EDITBOX和URl字符串 帮帮忙,提供一份辞职信样本 各位高手,帮我解决下处理BMP,位图的方法. SDI分割视图,不允许用户调整每个分割视的大小?怎么实现 很简单语法的问题。 蒸馏设备的原理?里面要加多少水?要蒸到什么时候?多长时间么时候?酿酒 人吃进的食物中的各种动物蛋白质和植物蛋白质,是怎样变成人体自身的蛋白质的? 为什么计算工程量时必须遵守计价规范中的工程量计算规则 求助一下大家奥数题大全就告诉我吧本人先在此谢谢各位4Z 问一下大家2013年最火的一道小学奥数题,求解!了解的说下吧,打心底感谢了7p 下列溶液中,在空气里既不易被氧化,也不易分解,且可以用无色玻璃试剂瓶存放的是?A石炭酸B氢硫酸C氢氟酸D醋酸(我就只知道C不行呀~) 六年级数学题大全 问一下大家2013年最火的一道小学奥数题,求解!了解的说下吧,打心底感谢了9p 、可用无色滴瓶存放较长时间的试剂是( )A.浓硝酸 B.BaCl2溶液 C.NaOH溶液 D.碳酸钠溶液在滴瓶里 也要考虑是否会与空气中物质发生反应吗?滴瓶密封性不好吗? 最好多一点 我想复习 C语言中\n的作用 有两个沙漏.甲沙漏漏完需要3分钟,乙沙漏漏完需要5分钟.两个沙漏同时开始漏沙.第一次、甲沙漏漏完后立有两个沙漏.甲沙漏漏完需要3分钟,乙沙漏漏完需要5分钟.两个沙漏同时开始漏沙.\x05第 麻烦大家看下奥数题大全n有点急, 请问下有谁知道2013年最火的一道小学奥数题,了解的说下吧,打心底感谢了5F 掘进工作面瓦斯大怎么办 送沙漏代表什么!我是男生,有一个男性朋友要过生日,我想送他一个沙漏.但不知道该送什么颜色的? 请问下有谁知道2013年最火的一道小学奥数题,了解的说下吧, 什么固态非金属单质是红色的? 绿色沙漏代表什么意思? 有什么东西的腐蚀性比香蕉水低我是做涂装的,公司用来遮蔽产品的塑料塞子(具体什么材值不清楚)时间长了塞子上就会累积很厚的粉,使用起来很不方便,用香蕉水泡下又会把塞子搞坏,求达人 红色的固态非金属单质都有什么黑色的呢? 世上最大的 峡谷是哪个峡谷 一个沙漏计时器,上下容器皆密封,若将此计时器内的沙子用水代替,则水会怎样?一个沙漏计时器,上下容器皆密封,若将此计时器内的沙子用水代替,则水会( )A.会流下来 B.C.可能会流下来 D.装 计算采用22.05KHz采样频率,16位采样精度,录制30分钟双声道立体声,其数据量大约为多少MB.(求答案以及计算过程,) 下列哪个峡谷是世界上海拔最高、最深、最长的峡谷? 能燃烧的固态非金属单质是 为什么天体都是圆的? 世界上最大的峡谷是哪里? 如果直线斜率为k 则倾斜角为arctan k 是否对(请祥解) 为什么所有的天体都是圆的 硫酸铜溶液与硫酸钠溶液为什么颜色不同 世界上最大的峡谷是什么峡谷? 采暖工程量如何计算?(计算规则) 如何除去硫酸亚铁中的硫酸钠并提纯硫酸铜原溶液中有硫酸亚铁,硫酸钠和硫酸铜,如何除去硫酸亚铁中的硫酸钠并提纯硫酸铜中的铜离子 世界上最长的峡谷 我有一瓶四氧化三铁试剂,请问有什么用或能做点什么越多越好 我国最大的三角洲是呃…… 日本和英国都是岛屿国家,日本多火山地震,而英国火山地震很少,为什么? 坚固的药剂瓶有什么用 结晶度的高低对聚合物性能有哪些影响 请帮忙说说几种换热器形式 白磷存放在装有水的试剂瓶中,金属Li存放在装有煤油的试剂瓶中这样的保存方法为什么错 什么是聚合物的结晶 请问有谁知道谁能做一道初中找规律的数学题?要用呀,打心底谢谢给位朋友了1d c语言中k+=n+1是什么意思 有同学将记录表中4次测量的电阻的平均值作为小灯泡的电阻,你认为这样做正确吗?为什么? c语言中 =n 怎么理解 初中化学有哪些固态非金属?高手快回答我 结晶度的大小对聚合物的性能有哪些影响? 润滑油对金属漆有腐蚀性吗请问汽车润滑油对金属表面喷漆或者刷的漆有腐蚀性吗 化学非金属与非金属非金属与非金属之间有些为什么可以反应有些却不可以反应 有什么规律没有?只在短周期中 为什么通过蒸馏就可以除去自来水中的氯离子等杂质?原理是什么,只有这种方法吗 机油有腐蚀性吗我经常用缝纫机油擦手电筒,这对手电有腐蚀吗. 化学非金属.在已经发现的一百多种元素中,除稀有气体外,非金属元素只有______种,它们大都位于元素周期表的______部分.地壳中含量最多的前两种元素是______和______.空气中含量最多的元素是____ 日本地震对相机影响会持续多久?什么时候能恢复正常?想买相机,结果就地震了.这次地震对数码影响究竟多大很多厂子都关了,松下停产.数码业全部涨价,这叫没影响? 请问航空油润滑油的话腐蚀性有一定的腐蚀性,那么容器采用何种材料或者热处理工艺来满足腐蚀性要求呢 采掘工作面的进风流中氧气和二氧化碳的浓度各有什么规定? 求内行来指点:有关地震导致数码相机涨价~想买个相机,春游用,可是目前单反都在涨,Canon600D,60D;NikonD90,D7000;……等等,商家都说有货,但是国美,大中这种地方,一分钱都不能降,标多少就是多 汽车机油腐蚀性强吗前几天去做保养,拆机滤的时候,机油淌下来都淌到球笼套上了,就是那个胶皮的套,我也让他们擦了,可是上面还是亮亮的,我有点担心会不会腐蚀了? 直线斜率 倾斜角与斜率大小的函数关系图像
备案号:鲁ICP备13029499号-2 说三道四 www.s3d4.cn 说三道四技术文摘