标准库中用于
调用 REST API 的库:
web.rest.client 请求参数使用urlencode 编码,服务器返回文本数据。web.rest.xmlClient 请求参数 使用urlencode 编码,服务器返回xml格式数据 。
web.rest. jsonLiteClient 请求参数 使用urlencode 编码,服务器返回JSON格式数据。web.rest. jsonClient 请求参数与服务器返回数据都使用JSON格式 。
除了与服务器交互的数据格式不同以外, 这几个库的接口用法完全一样,
可以看看这几个库的源码实际上他们都是调用 web.rest.client 这一个库。
web.rest 主要用于调用符合REST设计原则的 Web API,
并不适合用来替代 inet.http inet.whttp,curl等来实现非REST API用途的HTTP客户端。
REST API的URL一般会是这种格式 http://主机/资源目录名/资源目录名/资源名
而 web.rest.client 主要设计为支持将这类比较规范的API转换为AAuto中的普通函数。
下面用一个范例说明一下基本用法:
import web.rest.jsonClient;
// 创建REST客户端
var restClient = web.rest.jsonClient();
// 大括号里包含字母或数字指定占位符,AAuto并不关心占位符的实际内容,只关注他们出现的前后顺序
var restApi = restClient.declareApi( "http://服务器地址/api/g-{group}/u-{user}" )
/*
下面的调用使用的实际请求URL为 http://服务器地址/api/g-ecranesoft/u-crane
HTTP请求动词为 "POST",调用参数将会自动转换为JSON,而返回值将自动解析JSON生成对象
*/
restApi.ecranesoft.crane.post(
email = "web@ecranesoft.com" ;
password = "my password" ;
)
var restApi = restClient.declareApi( "http://服务器地址/api/{...}" )
/*
URL模板中的{...}占位符将会被资源名字替换,多个资源名字自动使用斜杠连接
使用的实际请求URL为 http://服务器地址/api/forums/user
HTTP请求动词为 "DELETE"
*/
restApi.forums.user.delete()
restClient.declareApi("API网址模板","HTTP请求动词")
该函数第一个参数为网址模板,在网址模板中可以使用花括号指定占位符,例如 {1} {user} 等等,
AAuto并不关心占位符的内容是什么,只关心它们出现的前后顺序,按顺序替换为对应的资源名字,如果不指定任何占位符,或占位符不够用了,资源名字将会用斜杠拼接到URL末尾。
HTTP规定了九种动词(Verbs)用于指定请求方法:GET,HEAD,POST,DEBUG,PUT,DELETE,PATCH,OPTIONS,
而在REST API中用到的有五种 GET,POST,PUT,DELETE,PATCH,他们的用途如下:
GET:用于获取数据
POST: 用于创建数据
PUT: 用于替换数据、也可用于更新数据
DELETE: 用于删除数据
PATCH:用于更新数据
restClient.declareApi() 的第二个参数可选指定一个默认的HTTP请求动词,如果不指定则默为"POST",
另外可以在调用API时可以显示的指定使用的动词,例如上面代码中的 restApi.forums.user.delete() 中显式指定了使用 DELETE 动词。
如量一个REST API在请求时需要上传、下载文件,那么所有调用规则如前不变,
你仅仅需要做的时,在调用API以前指定接受、或发送文件的回调函数以获取上传、下载的进度,
上传文件示例:
你仅仅需要做的时,在调用API以前指定接受、或发送文件的回调函数以获取上传、下载的进度,
上传文件示例:
restClient.sendFile( "上传文件路径"
,function(str,sendSize,contentLength){
..io.print("正在上传",sendSize,contentLength);
}
);
//在后面再简单的调用API就可以了,例如
restApi.upload()
下载文件示例:
restClient.receiveFile( "上传文件路径"
, function (str,receiveSize,contentLength){
..io.print( "正在下载" ,receiveSize,contentLength);
}
);
//在后面再简单的调用API就可以了,例如
restApi .download()