Web API核查表:设计、测试、发布API时需思考的43件事

当设计、测试或发布一个新的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操作;也就是说,“the side-effects of N > 0 identical requests is the same as for a single request.” (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语义意味着要与用户案例相匹配。更好地介绍,你可以阅读Darrel Miller写的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”,如果它没有接受“100 Continue”响应,在3秒的超时后会继续发送请求。如果API不支持“100 Continue”,或许会产生另一个性能缺陷,导致客户端禁用。

其它

40.文档:编写API文档是令人厌烦的,但是手写的API文档通常是最好的。编写时一定要包含这些内容:一些可运行的代码或者curl命令行,方便查阅。你也可以参考一些文档工具,例如:apiary.io、Mashery I/O Docs、Swagger。

41.设计与客户:不要在真空中设计API,要与客户打交道或者一起来设计API,参考用户用例。

42.反馈:在设计API时,应提供一个通道供用户进行反馈,

43.自动化测试:API测试是最简单的事情。它最好是自动化的,毕竟,需要好好利用它。

上面提供的这份列表有趣吗?对你是否有帮助呢?欢迎与我们一起讨论。

来自:Mathieu Fenniak

转载于:https://www.cnblogs.com/shanyou/archive/2013/04/23/3038583.html

本文来自互联网用户投稿,该文观点仅代表作者本人,不代表本站立场。本站仅提供信息存储空间服务,不拥有所有权,不承担相关法律责任。如若转载,请注明出处:http://www.mzph.cn/news/400705.shtml

如若内容造成侵权/违法违规/事实不符,请联系多彩编程网进行投诉反馈email:809451989@qq.com,一经查实,立即删除!

相关文章

[JSOI2007]文本生成器

1030: [JSOI2007]文本生成器 Time Limit: 1 Sec Memory Limit: 162 MBhttp://www.lydsy.com/JudgeOnline/problem.php?id1030Description JSOI交给队员ZYX一个任务,编制一个称之为“文本生成器”的电脑软件:该软件的使用者是一些低幼人群,他…

面试问题整理笔记系列 一 Java容器类

虚线框表示接口;实线框表示实体类;粗线框表示最常用的实体类;虚线箭头表示实现了这个接口;实现箭头表示类可以制造箭头所指的那个类的对象。 Collection:只允许在每一个位置上放一个对象。它包括“以一定顺序持有一组对…

【 Grey Hack 】反向Shell

目录调查准备反向shell反向shell提权版本:Grey Hack v0.7.3618 - Alpha 如图,本案例中目标IP尚未开放常见端口 调查 通过路由器获得目标PC的用户邮箱账号和相应的Password 所用脚本介绍: routerpsw 准备反向shell 在本机获得root后配置r…

leetcode------Word Search

标题:Word Search通过率:20.0%难度:中等Given a 2D board and a word, find if the word exists in the grid. The word can be constructed from letters of sequentially adjacent cell, where "adjacent" cells are those horiz…

阈值PSI代码

🚀 优质资源分享 🚀 学习路线指引(点击解锁)知识定位人群定位🧡 Python实战微信订餐小程序 🧡进阶级本课程是python flask微信小程序的完美结合,从项目搭建到腾讯云部署上线,打造一…

离散化求RECT1

本文转载至点击打开链接 #include<stdio.h> struct node{int x1,y1,x2,y2,c; }; struct node s[1010]; int px[2010],py[2010],ux[10010],uy[10010],p[10000]; short a[2010][2010],c[2510]; int main(){int i,j,k,m,n; scanf("%d%d%d",&n,&m,&k);…

对IplImage 结构体的理解

1 typedef struct _IplImage 2 { 3 int nSize; /* IplImage大小 */ 4 int ID; /* 版本 (0)*/ 5 int nChannels; /* 大多数OPENCV函数支持1,2,3 或 4 个通道 */ 6 int alphaChannel; /* 被OpenCV忽略 */ …

【 Grey Hack 】万金油脚本:原地提权工具

目录脚本源码用法效果及示例版本&#xff1a;Grey Hack v0.7.3618 - Alpha 脚本源码 metaxploit include_lib("/lib/metaxploit.so") if not metaxploit thenmetaxploit include_lib(current_path "/metaxploit.so") end if if not metaxploit then ex…

可落地的DDD(7)-战术设计上的一些误区

&#x1f680; 优质资源分享 &#x1f680; 学习路线指引&#xff08;点击解锁&#xff09;知识定位人群定位&#x1f9e1; Python实战微信订餐小程序 &#x1f9e1;进阶级本课程是python flask微信小程序的完美结合&#xff0c;从项目搭建到腾讯云部署上线&#xff0c;打造一…

android之PackageManager简单介绍

PackageManager相关 本类API是对全部基于载入信息的数据结构的封装&#xff0c;包含下面功能&#xff1a; 安装&#xff0c;卸载应用查询permission相关信息 查询Application相关信息(application&#xff0c;activity&#xff0c;receiver&#xff0c;service&#xff0c;prov…

【 Grey Hack 】万金油脚本:常见端口修改Password

目录脚本源码用法效果及示例版本&#xff1a;Grey Hack v0.7.3618 - Alpha 适用于SSH (22) 端口、FTP (21) 端口、HTTP (80) 端口、SMTP (25) 端口及3306/3307 端口等。 脚本源码 if params.len ! 2 or params[0] "-h" or params[0] "--help" then exi…

IPMI远程管理一点记录

http://www.07net01.com/storage_networking/IPMIyuanchengguanliyidianjilu_53093_1357975254.html转载于:https://www.cnblogs.com/diyunpeng/p/7001649.html

mysql INFORMATION_SCHEMA COLUMNS 解释

参考地址&#xff1a; http://dev.mysql.com/doc/refman/5.1/zh/information-schema.html#columns-table标准名称 SHOW名称 注释 TABLE_CATALOG 表目录 TABLE_SCHEMA 表架构 TABLE_NAME 表名 COLUMN_NAME Field 列名 ORDINAL_POSITION 列位置…

JavaScript中的原型和对象机制

1 对象相关的一些语言特性1.1 一切皆为对象JavaScript里所有的东西都是对象. 对象是属性的集合. 数字, 字符串, 布尔值等原始值是"伪对象", 它们同样拥有属性, 但是是在栈上分配并按值传递. 而其他的对象是堆上分配并按引用传递.一个很重要的概念是, 函数也是对象, 能…

【 Grey Hack 】记一次被黑经历

目录又被搞了版本&#xff1a;Grey Hack v0.7.3618 - Alpha 胆大包天的我黑进游戏内shop的IP后&#xff0c;顺着其上面的日志溯源到不少疑似其他玩家租的服务器&#xff0c;暂时没什么进展 不久后回到桌面才发现自己已经被黑入了 随后我打开日志查看记录 只看清是从我的1222…

iec61850采样协议(9-1、9-2)解析(一)

1 /*2 *3 * iec61850sv_protocol.h4 *5 * iec61850采样协议&#xff08;9-1、9-2&#xff09;解析。6 *7 *8 * 本代码支持win32平台和linux平台。9 *10 * Copyright (c)2012,lizhi<ibox>11 *12 * 2012-10-10 V1.0 lizhi<QQ:252240557,msn:ddgooohotmail.co…

C#即时释放内存

using System;using System.Diagnostics;using System.Runtime.InteropServices;[DllImport("kernel32.dll")]private static extern bool SetProcessWorkingSetSize(IntPtr process, int minSize, int maxSize);/// <summary>/// 即时释放内存/// </summar…

【 Grey Hack 】加强版nmap

目录probe使用方法效果routerpcscan使用方法效果版本&#xff1a;Grey Hack v0.7.3618 - Alpha probe if params.len ! 1 or params[0] "-h" or params[0] "--help" then exit(command_info("<b>probe [IP]</b>")) if not is_va…

文档容器iOS网络编程-iCloud文档存储编程实例

在本文中,我们主要绍介文档容器的容内,自我感觉有个不错的建议和大家分享下 iCloud文档存储程编对相键值据数存储而言比较复杂&#xff0c;涉及到自定义文档类、取得iCloud文档录目、找查Ubiquity容器中的文档、保存文档和决解文档冲突等容内。 实例&#xff1a;iCloud文档存储…

CSS3之伪元素选择器和伪类选择器

伪类选择器&#xff0c;和一般的DOM中的元素样式不一样&#xff0c;它并不改变任何DOM内容。只是插入了一些修饰类的元素&#xff0c;这些元素对于用户来说是可见的&#xff0c;但是对于DOM来说不可见。伪类的效果可以通过添加一个实际的类来达到。 a:link|a:visited|a:hover|a…