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

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

Oracle数据库Windows 2003环境自动备份批处理 VB通过ADODB连接EXCEL表格文件读取数据 使用VBScript卸载软件 Discuz X2用户注册过程SQL Android手机参数表 用jQuery改变图片(image src) 用std::atomic實現簡單的讀寫鎖 ChinaPay网上支付网关.NET开发 VOB生成IFO文件用nero刻录DVD详解 15款开源Android游戏引擎(安卓免费游戏引擎) 将MVC ASPX转换到Razor视图 Word设置目录简明教程 asp.net mvc页面javascript代码中如何使用razor Discuz X论坛数据表结构:用户数据表pre_common_member boost在windows平台下自带超强 IOCP 的ASIO Boost下载和编译安装简明指引 Windows和Linux环境中Boost下载安装编译配置使用指南 Android开发技巧:Android常用类库说明 Android开发技巧:Android 文件系统 Android开发技巧:Android应用程序架构 ASP.NET MVC Razor 输出没有编码的HTML字符串 ASP.NET MVC 3 Razor 在head里包含js文件 JQuery mobile介绍 JQuery Mobile 页面结构 什么是云计算的通俗理解 什么是Hadoop以及与云计算的关系 创建一个Windows Phone 7推箱子益智游戏 好用的在线编辑器百度UEditor ASP.NET如何从URL或route数据中得到controller类型和action信息 Discuz X论坛数据表结构:论坛主题数据表pre_forum_thread Discuz X论坛数据表结构:论坛帖子数据表pre_forum_post 有人知道如何在application中取出拨号地址的吗? 这不公平!!!!!!! Delphi 指针问题,请大家帮忙! web assistant怎么根据数据库中的数据生成一个页面?那个页面要我自己的样式? 大家帮我看看错在那里!谢谢! 请问有没有用自己的机子作服务器的? 帮我看看代码 日志钩子的安装问题? 如何使用。MDB文件 由于上一题回帖子的人数众多,导致分数不够,所以再开一帖!继续!关于用vb进行文件的读写问题! 怎样在数据库中输入了许多条记录后, 一次性存盘成功? 改变光驱盘符?很急很急 在Oracle中怎样加已经存在的数据文件? 我想请高手帮忙 !! 请问目前那一本参考书对DELPHI初学者有很大提高? 一个关于udp重发的问题 如何在delphi程序里调用vc写的exe执行文件。 如何将query中的内容输出到文本文件,然后还能将该文本文件再导入进来?急急急!!!!!!!!!!! 急急急!!我的计算机找不到硬盘了45分 如何求任意多边形的重心 紧急求助:请问java有没有比较丰富的多媒体控件?比如录音的控件??? 急急急!!!我的计算机找不到硬盘了,45分 如何把一个字段的内容求和,然后把结果存入另一表! 请教,怎样把一个记录数组用VB读入ACCESS 2000数据库中? 关于货币类型的问题? the script too large ????????我快疯了。 什么地方有Sybase与Oracle的比较资料? 急急急!!!我的计算机找不到硬盘了,40分 问一下大家 复活节彩蛋 win2000 professional下如何配置weblogic6.0 jsp和javasript如何通讯? 急!!!如何把'¥100'字串转化为浮点型100.00 用OleContainer1将一个WORD文档存进数据库后如何将它从数据库中取出??? 关于SNMP的问题(请高手回答,送40分) 谁想过要戒水?戒成了吗?又渴了吗? 我用在各种机器上使用Win2000,从来没有down过, 真是太奇怪了??? 请问如何确定操作系统系统是中文的还是英文的? 向外国用户发注册码时候应该说些什么,才能让别人觉得你比较专业? 如何捕获ADO的异常信息 struct结构的数据存储是用的什么顺序方式呀? 能介绍几本关于BCB的适合初学者阅读的书吗? 高手进来,struct结构的数据存储是用的什么方式呀 高分!高手请进!!! Newton 有关StoredProc的 各位大虾进来看看,Debug时的错误~~~~~~~ First-chance exception 和 User breakpoint ,帮帮我啊!!! 虽然我也回复没有分,但有意思的帖子,但我对分数高的帖子更有热情,我是不是很势利?? 我的服务器是unix 哪位提供最简单的图片存入库中的代码 谁能得到拨号上网所使用的电话的号码? 英语有哪些标点符号 英语翻译我想写一封信给Daniel,不过我的英语不行,请帮我翻译一些句子,请不要发在线翻译的结果给我,1 哈利波特系列是我最喜欢的书之一.读书的时候我的思绪在奇妙的魔法世界游走,但在看 联想笔记本键盘字母变数字? 英文里为什么很少用标点符号?印象中括号,引号,破折号都很少见,书名号更是根本没有,常用的只有逗号句号和问号,偶尔能看到个引号.这是为啥捏?3Q 英语翻译新年期间收到叔叔的一封邮件,内容是:叔叔们准备寄700美元回家乡给我们过新年,但是到目前为止,我们并没有收到关于这700美元的任何信息!在发这封邮件之前,我已经发过两封邮件 下面的字母各代表什么数字?(不同字母代表不同数字.)a 0 b c 3 - x 7 2 y =7 7 7a=?b=?c=?x=?y=? 英语翻译英文句子里电影名字是用《》书名号括上,还是用“”引号括上? 英语翻译Hello,My name is Loyce Agurma,I came acrose your profile hi.baidu.com I felt it and decide to send you a massage,to ask you for friendship .you know having a prophesy of love over someone there most be odds around the,but no matter the od 下面算是中相同的字母代表相同的数字,不同的字母代表不同的数字.每个字母各表示什么数字? 填写标点符号, 如何写英文祝贺信 手机ID号是按哪些数字和字母啊? 标点符号填写1雨的力量在于它可使一望无际的黄土高原转眼变得沟沟壑壑()混乱不堪()而知识的力量则在于它可改变命运()扭转乾坤(),缔造美好的未来.2不要在光线暗的地方看书( 这封信怎么写?英语Contact person是 Julie Murphy,公寓名字是Medical Center Apartments.它有三种,1 bedroom,2 bedroom和3 bedroom,我想选这个3 bedroom,住6个人最划算的这个. Photoshop选颜色画面的下面前面带#号的选项 ,有是全是数字有时全是字母有时是数字字母组合那个选项是做什么的? 填写标点符号 字母找规律1、BEH,ELM,LN( )2、CFL,FKP,KR( )3、KFP( ).DML( ) 4、ELN( ).ADG( ) 沪牌照沪+字母 字母+四位数字的号码和沪+字母 +全数字的有什么差别?现在上海的私车牌照有的是比方:沪D H1234,有的是沪D 12345 这两种牌照有什么差别? 问一个标点符号书写问题如果用格子信纸书写到每一行还有一个空格时,这时正好这句话还差一个字,如果加上句末的标点符号就需要两个空格了.通常遇见这种情况下是不是这最后一个空格就 英语字母找规律A,S,D,F,G,H,J_,_.请问该填什麽?规律是什麽? 数字30~40用英语怎么写?35~40的就可以了~ 名信片的英语怎么写 看字母 找规律ABAABAAABAAAABAAAAABAAAAAAB.按以上的规律,那么前2005有几个B 英语数字1-30 英语比赛,要写一篇英语作文,布置怎么写英语信. 我想给字母找规律根据提示写字母A D G D I N I P ( ) 用括号内所给单词的适当形式填空.1、If my bank manager ______(lend) me the money,I______(buy) a new car next month.2、I______(have)to go to see the doctor tomorrow.3、If you bring friends from other schools,the teacher ____(ask) them "英文怎么写?你...以上英文怎么写? 找规律填字母.(1)K F P () (2)E I N () A D G ()D M I ()(1)K F P ( ) (2)E I N ( ) D M I ( ) A D G ( ) 用括号中所给的动词的适当形式填空(英语)My grandfather___(go)to the park every morning.They are____(have)a lesson now.The teacher is_____(stand)in front of the blackboard.He____(paint)his desk black last week.I______(此处填 英语信怎么写 During the summer holiday there will be a new schedule.C 1 for meal and l 2 service hours and for bus schedules will appear on the wall outside the dining room.We are making weekly film and concert schedules.They will a 3 each Wednesday outside the l 谁能帮我做一下这几道英语题 (用括号内所给的适当形式填空)1 ) How many * (time) did he orbit the Earth?2)The plane landed * (safe)in shanghai.3)The boy * (bear)in 1993.4)Jack and I * (be) late for school yesterday.5)T 《信我 》的英文怎么写 潮州话数字1-10和26个英文字母怎么读?和普通话发音不同的请注明读音,0,2,5,10怎么读?用汉字表示出来好吗? 用括号中所给词的正确形式填空①Which month is the_____(nine)month?②______(sixty-two)students are in our class.③May 10th is her brother's______(thirty)birthday.④Mr Wu is on______(twelve)floor of the building.⑤Tom is_______(thre 我喜欢你 你信么英语 (英语题)根据首字母填空(10题)1.Monica h_____ three books and apencil case.2.Do you h_____ a baseball bat?3.Let's p_____ soccer.4.That's _____ interesting.5.I don't w_____ TV in the evening.6.How do you s_____ pencils?7.There are so 英语题目用括号内所给的正确形式填空that sign means “no【 】【litter】there are a lot of【 】【photo】on the deskare they【 】【make】model planes now?the old man often【 】【touch】the tree thereplease come here【 我说我喜欢你,你信不?英文怎么翻译 英语首字母填空 急! 所有空都得填出来(数清了,是10个空)"Be careful" is used very often in China to show care f______ others. But in Britain it sounds like giving an order or w_______. You could say that to younger people but n_____ 用括号中所给的单词的适当形式填空(英语)Today she____(like)basketball,but she_____(enjoy)playing volleyball in five years. 见信速回用英语怎么写 衣服码号有数字的,有英文字母的,到底多大的号对多大的码? 请用括号内所给单位的适当形式填空.一、请用括号内所给单位的适当形式填空.1.I can’t____(help)you now.2.There are brown____(desk)in the classroom.3.---Is this____(she)bike?---Yes,it is.4.I often____(do)t 他在信中写了什么吗 用英语怎么说 用户名由6-20位长度的数字,英文字母和标点符号组成,至... 英语题(用适当形式填空)1.I_____ just ______(finish) my homework.2.He ________(go)to school on foot every day.3._______you ________(find) your science book yet?4.If it _______(be) fine tomorrow,I'll go with you.5.I've lost my pen.________you 昨晚我写了一封信(求英语翻译) ORACLE SQL 获取26个大写英文字母A-Z形如:字母ABCD……Z不用union的方式 英语适当形式填空 这题怎么做?These dresses______(look)nice on ______(they) 输入的中文标点符号与英文标点符号有什么区别?中文标点符号与英文标点符号主要是什么功用. 英语信怎么写啊 caxa如何将标注中的数字尺寸换成英文字母?我选编辑-文字内容,经常改不了,还是数字而不是字母,为什么? 怎样切换中文标点和英文标点? ( )the( )( )English?翻译:这封信是用英语写的吗? 笔记本键盘上的英文字母为什么会变成数字?有时候玩着玩着这些英文字母J I O L M U 都会变成数字 一些数字34560 就会按出来是#¥%……这样子为什么会这样?打问号还会变成+ 为什么 笔记本上 关于英文里的标点符号今天上课就是讲这个..听不太懂....不是句号实不实心的问题...是想问在句子中分段的用法.. 英语翻译MIKE JASON先生您好:在北京的机械展览会上,有幸认识您十分的高兴.我公司是经营脚轮,履带板翻新等项目.希望能与贵公司合作.下面是我公司的联系方式天津XX脚轮厂地址:天津市河东区 华硕笔记本键盘的字母变数字了,怎么回事我按键盘的u i o j k l m 是数字 4 5 6 1 2 3 0 请问下是怎么回事啊?怎么才恢复得过来呢?
备案号:鲁ICP备13029499号-2 说三道四 www.s3d4.cn