使用 web.rest 调用 REST API



标准库中用于 调用 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以前指定接受、或发送文件的回调函数以获取上传、下载的进度，

上传文件示例：

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