使用 web.rest 调用 REST API


标准库中用于调用 REST API 的库：

[align=left]web.rest.client 请求参数使用urlencode编码,服务器返回文本数据。[/align]
web.rest.xmlClient 请求参数使用urlencode编码,服务器返回xml格式数据。

web.rest.jsonLiteClient
请求参数使用urlencode编码,服务器返回JSON格式数据。
[align=left]web.rest.jsonClient 请求参数与服务器返回数据都使用JSON格式。[/align]

除了与服务器交互的数据格式不同以外, 这几个库的接口用法完全一样，

可以看看这几个库的源码实际上他们都是调用 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以前指定接受、或发送文件的回调函数以获取上传、下载的进度，

上传文件示例：

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()