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

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

$.recallDroppables()-JQuery API $.SortSerialize()-JQuery API Draggable(hash)-JQuery API DraggableDestroy()-JQuery API Droppable(options)-JQuery API DroppableDestroy()-JQuery API Sortable(options)-JQuery API SortableAddItem(elem)-JQuery API $.meta.setType(type, name)-JQuery API data()-JQuery API disableTab(position)-JQuery API enableTab(position)-JQuery API tabs(initial, settings)-JQuery API triggerTab(position)-JQuery API triggerTab(position)-JQuery API Tooltip(settings)-JQuery API PHP简介-PHP初学入门教程1 选择PHP的理由 -PHP初学入门教程2 从一个简单的程序来了解PHP -PHP初学入门教程3 PHP语法基础 -PHP初学入门教程4 建设一个简单的交互网站(一) -PHP初学入门教程5 建设一个简单交互的网站(二) -PHP初学入门教程6 建设一个简单交互的网站(三)密码验证 -PHP初学入门教程7 PHP文件上传 -PHP初学入门教程8 为站点添加投票功能 -PHP初学入门教程9 广告条轮播-PHP初学入门教程10 操作MySQL数据库实现简单的留言板-PHP初学入门教程11 使用PHP来操作Oracle数据库 -PHP初学入门教程12 技术杂项PHP教程结束篇 -PHP初学入门教程13 .NET中DataSet和DataReader的区别与转换 CGI技术及其开发(二)-Delphi资料 有关使用DirectShow开发TV Capture的问题 如何声明和使用自定义对象(如:Tdadaset)的事件?? PB的数据窗口中GerRow()得到的不是具有焦点的行,如果我要想的到具有焦点的行,应该用什么东东 有关使用DirectShow开发TV Capture的问题(一定给高分) 在VB中能否将时间格式化为显示出毫秒来? 寻求驱动 如何给回答我问题的人加分? 如何在mshflexgrid中输入字符 如何改变当前打印机的纸型? 请问在WINXP下的怎设置IIS? 我在用 DataReport 控件对数据库进行输出时 为什么运行时总是弹出选择数据库的对话框? 这个数据库连接不是已经设置好了吗? 怎样取消textbox的凹凸感? 为什么在IE6 中使用Ctrl+Shift组合健得到的连接是http://www.china.co.cn 为什么总是出现Invalid BLOB handle in record buffer错误 大家晚上好,怎么让我的程序里有一小块是网页的内容呢?(全部家档!!) 关于Database和Session的问题!火急!(快乐的程序员) jsp+mysql如何在linux上配置 有知道黑龙江高程查分方法的吗????? *******我要一个这样的类:显示淡入淡出的菜单(最好还能有半透明的功能) *************** 特急,各位帮忙。怎么样在字符串中包含'(单引号)? 高分求助用paradox数据库保存JPEG图片的代码,我试过网上好多都没成功。markoni@21cn.com 吴文智、袁飞、Jinesc、Jneu、Amoon、ttyp、icevi、progame 快请进 请教一个表与表之间比较数据的问题,由于数据量大,造成事务不够,请教解决方案 execcommand的使用方法求救。高手请进,一定给分。 我的时钟怎么回事? Matlab论坛 打印机的取消按钮 dbgrid中当某个单元格失去焦点时触发什么事件? 关于Database和Session的问题!火急! yanxu1 学习unix下的c编程,该如何学?请介绍方法,资料什么的--我对unix和c都还熟悉。 打印机死机作何解?????? 我是新来的,请各位大哥、大姐们多多关照!!!(有内容) 再次发问关于sql server7的问题?? SQL SERVER中的一个触发器的问题!!! xml里有什么method可以取得子节点在父节点中的位置(序号)? please help me 怎么样才可以把系统存储过程的结果写到结果集里? 如何声明和使用自定义对象(如:Tdataset)的事件(beforecancel)?? 一个奇怪的问题? 各位兄弟,谁知道哪里有pb7的下载? 天呐 我提的问题从来没人回答 SQL Server小小问题 请问那里有DELPHI第二张光盘下载! 如何是使用describe来获取datawindow中的带区参数? 谁有早期的TeeChart5.ocx,文件大小为2,576,384,发行日期在2001-06-17号以前的,我这里有个crack软件,但是新下载的不行,所以重金寻求!!! 请问C语言中有字符串查找函数吗? 请问如何动态的改变应用程序的图标,一定给分 Query主从表编辑问题,从不丢失! 急急急!!!! 高分求禁止IE的自动谈出的广告,有个软见也行,或者告诉实现方法。请告诉下载的网址。 打印一些清单在delphi中用哪些控件比较好? 一满桶水用去了一半后,又加水3千克,现在桶里面的水是原来的5分之3.这桶水原来有多了千克? 一个鱼缸的长宽高分别是5dm,3dm,4dm,浴缸中的水面高20厘米,若里面放进体积为18dm3的石块并且完全浸没在水中,水面离缸口多少dm?(要算式) 甲乙两个加油站,间距为3600米,路旁有路标,原来40米一个(起点,终点各有一个),现在要改成50米一个,将有多少旧路标可以留用 有三条公路相交于A B C三点,要在这三条公路旁边造加油站,使它到公路的距离相等,满足条件的加油站可以几个? 一家酒店,地面上18层,地下1层,地面上1楼为接待处,顶楼为公共设施处,其余16层为客房,地面下1楼为停车场.(1)某会议接待员把汽车停在停车场,进入该层电梯,往上14层,又下5层,再下3层,最后上6 4.某路公共汽车,包括起点和终点共有15个车站,有一辆车除终点外,每一站上车的乘客中,恰好有一位乘客到以后的每一站下车,为了使每位乘客都有座位,问这辆公共汽车最少要有多少个座位? A B C 是三个加油站,现在要在这三点之间建一个储油库,使它到三个加油站的距离相等.图 B.A ..C我好像记得 姐说过可以有三个地点 一家饭店,地面上18层,地下1层,地面上一楼为接待处,顶楼喂公共设施处,其余16层为客房,地面下一楼为停场.(1)某会议接待员把汽车停在停车场,进入该层电梯,往上14层,又下5层,再下3层,最后上 地下停车库入口坡道多少米? 如图,三条公路两两相交于A,B,C三点,现计划建一座综合供应中心,在△ABC内部要求到三个顶点的距离相等请你找出符合条件的地点 一饭店地面上18层,地下1层,地面上1楼为接待处,顶楼为公共设施处,其余16层为客房;地面下1楼为停车场一家饭店,地面上18层,地下1层,地面上1楼为接待处,顶楼为公共设施处,其余16层为客房;地 为缓解“停车难”的问题,某单位拟建造地下停车库,建筑设计师提供了该地下停车库的设计示意图为标明限高,请你根据该图计算CE.(精确到0.1m)图 方法,不要方程,百分之一百全对一个长方体容器,占地面积3平方分米.将一个梨放入其中,并完全没入水中,水面升高了0.1dm.这个梨的体积是多少立方厘米 一家饭店,地面上18层地下1层地面上1楼为接待处顶楼为公共设施处其余10层为客房地下1楼为停车场客房七楼与停车场相差 层楼一家饭店,地面上18层地下1层地面上1楼为接待处顶楼为公共设施 转基因大米对人有危害吗 长方体容器,占地面积3立方分米,放入一个梨后水面升高了0.3分米,梨的体积是多少占地面积3平方分米 合肥市庐阳区某路段新建一家饭店,地面上18层,地下一层,地面上一楼为接待处,顶楼为公共设施处,其余16层为客房,地面下一楼为停车场.某日,电梯检修停电,一服务生在停车场停好汽车后,只能 数学题:为了缓解“停车难”的问题,某单位拟建造地下停车库,建筑设计师提供了地下停车库的设计示意%C地下停车库坡道口上方要张贴限高标志,来告知停车人车辆能否安全驶入,为标明限高, 一个长方体容器底面长5分米宽4分米放入一个西瓜后水面上升了0.3分米这个西瓜的体积是多少立方分米因为字数太多了,请自己辨认隔开.这个问题没有高.要今天8点之前, abc三条公路如图所示,现在要建一个货物车站,是他到这三条公路的距离相等,做图思路 转基因大米有什么不好 一桶水,倒出60千克,刚好倒出40%,这桶水共有多少千克.不用算式 什么是转基因大米 数学题为缓解“停车难”的问题,某单位拟建造地下停车库,设计师提供了车库入口设计示意图(下图),按规定为缓解“停车难”的问题,某单位拟建造地下停车库,设计师提供了车库入口设计示意 直线a、b、c表示三条互相交叉的公路,现要建一个加油站p,要求点p到三条公路的距离相等,有几种选择?如何选 某商场有一自动扶梯,小明以速度v沿开动(上行)的自动扶梯走上楼时,所用时间为T1,当他以相同的速度沿开动(上行)的自动扶梯走下楼时所用时间为T2,则该自动扶梯上行的速度为多少? 为了缓解“停车难”的问题,某单位拟建造地下停车库,建筑设计师提供了地下停车库的设计示意为了缓解“停车难”的问题,某单位拟建造地下停车库,建筑设计师提供了地下停车库的设计示意 一个长方体容器,从里面量长宽均为2分米,向容器中倒入3.5升水,再把一个石头放入水中,这时量得容器内的水深是25厘米.这个石头的体积是( ). 顾客站在商场自动扶梯的水平台阶上随自动扶梯匀速上升.顾客在上升过程中(c) A、机械能保持不变 B、运动状态在不断变化 C、相对于其站立的台阶是静止的 D、受到重力、支持力和摩擦 3路:每隔6分钟发一次车 5路:每隔8分钟发一次车 3路和5路的起点站都在这儿. 它们刚才同时发的车.这两路公共汽车同时发车以后,至少过多少分钟两路车才第二次同时发车?要过程! 一个长方体玻璃容器,从里面量长4分米,宽3分米,里面装有水2.4升,再把一块石头放入水中.这时量得容器内水面高是5厘米.这块石头的体积是多少? 小明站在超市的自动扶梯上,随着自动扶梯匀速上升的过程中,小明()A.动能转化为势能,机械能减小B.只受到重力与支持力的作用C.如果选“自动扶梯”为参照物,小明是运动的D.自动扶梯对小 把7分之4千克的黄豆平均分成6份,每份是1千克的几分之几,每份是4千克的几分之几.马上要交了. 一个长方体玻璃容器,从里面量长宽均为3分米,向容器中倒入7.2升水,再把一块石头放入水中(石头完全浸入水中,水为溢出)这时量得容器内水深9厘米,这块石头的体积是多少? 乘超市的自动扶梯,自动扶梯的长度是22,求小明的速度与自动扶梯的速度的数学问晓明顺着扶梯的方向走,用了一分钟,用同样速度逆着走,用11分钟,自动扶梯的长度是22米, 一条72米长的路,原来从一端起,每隔9米有一盏灯(起点和终点都装有路灯).现在一条72米长的路,原来从一端起,每隔9米有一盏灯(起点和终点都装有路灯)。现在重新安装,要从一端起每 为了测量一个石块的体积,在一个长10分米、宽6分米、高4分米的长方体容器中放入适当的水,再把石块放入水中这时长方体中的水面上升了15厘米,求石块的体积是多少立方分米? 7明明和玲玲每个都有一些本子,如果明明给玲玲2本,两人就一样多,如果玲玲给明明1本,明明的本子就是玲玲的7倍.问明明和玲玲各有多少本子 不能用方程解 一栋大楼地下共4层地上共18层史师傅从地下4层到地上3层用了7/60分钟王老师乘电梯从地下3层到地上7层需多少分钟?(算术) 一个长方体容器里面量长四分米宽三分米相容器中到十八升水把一块石头的没入水中这时量的容器内水深28厘米石头的积是多少 "一栋大楼共20层.李叔叔乘电梯从地上10层到地下9层要20分之3李叔叔乘电梯从地下8层"到地下一层车库要多少分钟 一栋大楼地下4层,地上有18层,史师傅乘电梯从地下4层到地上4层,要六十分之七分钟,王师傅乘电梯从地下4层到地上7层,用多少分钟 这是转基因玉米吗 一个长方体的总和是60cm,它正好能被切成3个同样的正方体.原来的长方体的表面积是? 把三个棱长1cm的正方体拼成一个长方体,长方体的表面积是18cm2吗? 【数学应用】小红的爸爸想在本镇的3条交叉公路处建一个加油站,要求它到三条公路的距离相等.小红的爸爸想在本镇的3条交叉公路处建一个加油站,要求它到三条公路的距离相等,这样可供选 转基因的危害 转基因大米什么样 用5个棱长为1cm的小正方体拼成一个长方体,这个长方体的表面积是多少平方厘米? 有三条公路相互交叉,现在公路围成的空地上要修建一座加油站,使它到三条公路的距离相等,问加油站该修建在什么位置? 一个长60cm,横截面是正方体的长方体.如果长增加6cm,表面积就增加96cm,求原来长方体的表面积和体积. 某人乘电梯从地下2层上升18层后,发现自已走错了楼层,又下降了3层,此人现在在处级 鱼缸长4宽3深2把一个石头放入身高了0.8,石头体积多少 单位是分米哦快, 转基因大米人吃了有什么危害 有一段长340米的马路,要在这条马路的两侧植树.从一端为起点,每隔8.5米中一棵树,一共要种多少棵树 一个鱼缸长1m,宽3dm,高4dm.将一条鱼放入鱼缸后,水面由3dm升至3.12dm.鱼的体积是多少? 一个长方体棱长总和60Cm,正好切成3个相同的正方体,原长方体体积是? 在一条长600米的公路两边植树,要求每边都每隔3米栽一棵树,如果从公路的起点栽起,一直栽到终点,一共需要多少棵树苗? 王老师将一满桶水用去一半后,又加水3千克,现在桶里的水是原来的5分之3,这桶水原有多少千克?3÷(3/5-1/2)这种做法是什么意思, 一个鱼缸的长 宽 高分别是5dm 3dm 4dm,鱼缸中的水面高是2分米,若从里面放进积为18立方分米的石块,水面离缸口多少分米? 每瓶饮料Xml,5瓶这样的饮料平均分给3个同学,每人可分到多少ml?
备案号:鲁ICP备13029499号-2 说三道四 www.s3d4.cn